smishchuk/svc-api-x
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

cleanup: remove reasoning comments and translate helper docs

Browse Source
This commit is contained in:
Naeel
2026-04-29 20:51:44 +04:00
parent f6d5c868cb
commit 7b98eee156
6 changed files with 145 additions and 161 deletions
Download Patch File Download Diff File Expand all files Collapse all files
v1/lib/rest_api_helper.cfc
+23 -92
View File
@@ -1,18 +1,17 @@
<cfcomponent
displayname="ReST API helper"
output="true"
hint="Static helper methods for ReST API">
hint="Статические вспомогательные методы для ReST API">
<cffunction name="empty2null"
access="public"
returntype="any"
output="false"
hint="replace empty field with null">
hint="Заменяет пустое поле на null">
<cfargument name="value" type="any" required="true" />
<cfif isSimpleValue(ARGUMENTS.value) AND isEmpty(ARGUMENTS.value)><!---*** некорректно, но просто, пустые строки превращает в нулл--->
<!--- нам не нужно, чтобы пустые массивы превращались в нулл. Наверное, и структуры тоже --->
<cfif isSimpleValue(ARGUMENTS.value) AND isEmpty(ARGUMENTS.value)>
<cfreturn javacast('null','')/>
<cfelse>
<cfreturn ARGUMENTS.value />
@@ -23,7 +22,7 @@
<cffunction name="passThrough"
returntype="any"
output="false"
hint="just return argument">
hint="Возвращает аргумент без изменений">
<cfargument name="x" type="ANY" required="true"/>
<cfreturn #ARGUMENTS.x#/>
</cffunction>
@@ -33,7 +32,7 @@
access="public"
returntype="any"
output="false"
hint="put data into struct, replace empty fields with null">
hint="Записывает данные в структуру, заменяя пустые поля на null">
<cfargument name="struct" type="struct" required="true" />
<cfargument name="key" type="string" required="true" />
@@ -65,9 +64,7 @@
<cfif queryColumnExists(ARGUMENTS.query, local.col)>
<cfset obj[ARGUMENTS.fieldNameDecorator(local.col)]=empty2null(formatter(ARGUMENTS.query[local.col][ARGUMENTS.query.currentRow]))/>
<!--- *** преобразование пустой строки в null преобразует в нулл также пустые списки, что искажает факт --->
</cfif>
<!---*** не уверен в надежности конструкции во всех реализациях CF, контекст query передастся ли--->
</cfloop>
<cfreturn ARGUMENTS.struct/>
@@ -78,13 +75,10 @@
<cffunction name="parseFilterParams"
returntype="array"
output="true"
hint="Parse and collect filter params from URL. For operators see filter_build">
hint="Разбирает и собирает параметры фильтра из URL. Операторы задаются в filter_build">
<cfargument name="params" type="struct" required="true" />
<!--- используется альтернативный парсер query_string, чтобы не путать запятые в значении с разделителями списка list --->
<!--- имена полей в URL в snake_case или camelCase, имена колонок в snake_case --->
<!--- token example minSize=NEQ:2--->
<cfset var local = {}/><!--- *** --->
<cfset var local = {}/>
<cfset var out = []/>
<cfset var urlParams = parseQs()/>
@@ -93,7 +87,7 @@
<cfset var urlParamName=snake2camel(lCase(local.item))/>
<cfif structKeyExists(urlParams,urlParamName)>
<cfloop array=#urlParams[urlParamName]# item="local.rawValue"><!--- when parameter occures in URL more than once, its values compose a comma delimited list --->
<cfloop array=#urlParams[urlParamName]# item="local.rawValue"><!--- Если параметр встречается в URL несколько раз, его значения образуют список через запятую. --->
<cfset var operator="EQ"/>
<cfset var value=#local.rawValue#/>
<cfif listLen(local.rawValue,":") GT 1>
@@ -134,12 +128,10 @@
<cffunction name="parseFilterParamsV1"
returntype="array"
output="true"
hint="parse and collect filter params, for operators see filter_build">
<!---e.g. duration=NEQ:2--->
<!---*** add test for multiple values--->
hint="Разбирает и собирает параметры фильтра; операторы задаются в filter_build">
<cfargument name="params" type="struct" required="true" /><!--- имена полей и колонок в snake_case --->
<cfset var local = {}/><!--- *** --->
<cfset var local = {}/>
<cfset var out = []/>
<cfloop collection=#params# index="local.item">
@@ -147,7 +139,7 @@
<cfset var urlParamName=snake2camel(lCase(local.item))/>
<cfif structKeyExists(URL,urlParamName)>
<cfloop list=#URL[urlParamName]# item="local.rawValue"><!--- when parameter occures in URL more than once, its values compose a comma delimited list --->
<cfloop list=#URL[urlParamName]# item="local.rawValue"><!--- Если параметр встречается в URL несколько раз, его значения образуют список через запятую. --->
<cfset var operator="EQ"/>
<cfset var value=#local.rawValue#/>
<cfif listLen(local.rawValue,":") GT 1>
@@ -189,7 +181,7 @@
<cffunction name="parseOrderBy"
returntype="struct"
output="false"
hint="parse and collect sort order param"><!--- deprecated --->
hint="Разбирает и собирает параметр сортировки"><!--- Устаревший метод --->
<cfargument name="params" type="struct" required="true" />
<cfargument name="orderBy" type="string" required="true" />
@@ -203,7 +195,7 @@
<cfcase value="ASC"><cfset var asc=true/></cfcase>
<cfcase value="DESC"><cfset var asc=false/></cfcase>
<cfdefaultcase>
<cfthrow type="InvalidParamValue" message="Invalid orderBy format" detail="orderBy suffix should be '.asc' or '.desc'" /><!---*** XSS vulnerability, so we would not show the suffix--->
<cfthrow type="InvalidParamValue" message="Invalid orderBy format" detail="orderBy suffix should be '.asc' or '.desc'" /><!--- Суффикс не возвращается пользователю, чтобы не расширять XSS-поверхность. --->
</cfdefaultcase>
</cfswitch>
<cfelse>
@@ -223,7 +215,7 @@
<cffunction name="parseNumericOrder"
returntype="array"
output="false"
hint="parse and collect sort order param with numeric notation">
hint="Разбирает и собирает параметр сортировки в числовой нотации">
<cfargument name="fieldSet" type="struct" required="true" />
<cfargument name="orderBy" type="string" required="true" />
@@ -237,7 +229,7 @@
<cfcase value="ASC"><cfset var asc=true/></cfcase>
<cfcase value="DESC"><cfset var asc=false/></cfcase>
<cfdefaultcase>
<cfthrow type="InvalidParamValue" message="Invalid orderBy format" detail="orderBy suffix should be '.asc' or '.desc'" /><!---*** XSS vulnerability, so we would not show the suffix--->
<cfthrow type="InvalidParamValue" message="Invalid orderBy format" detail="orderBy suffix should be '.asc' or '.desc'" /><!--- Суффикс не возвращается пользователю, чтобы не расширять XSS-поверхность. --->
</cfdefaultcase>
</cfswitch>
<cfelse>
@@ -252,35 +244,9 @@
</cfloop>
<cfreturn out/>
</cffunction>
<!---<cffunction name="snake2camel"
access="public"
returntype="any"
output="false"
hint="convert snake style name to camel style name">
<cfargument name="snake" type="string" required="true" />
<cfset var snake=ARGUMENTS.snake/>
<cfset var camel=""/>
<cfset var pos=1/>
<cfloop condition="true">
<cfset next=reFind("(_[a-z])", snake, pos, false)/>
<cfif NOT next GT 0>
<cfbreak/>
</cfif>
<cfset camel="#camel##mid(snake,pos,next-pos)##uCase(mid(snake,next+1,1))#"/>
<cfset pos=next+2/>
</cfloop>
<cfset camel="#camel##mid(snake,pos,len(snake))#"/>
<cfreturn #camel#/>
</cffunction>--->
<!---not used any more--->
<!--- Больше не используется --->
<cffunction name="query4json" access="public" returntype="any" output="false"
hint="Converts query to an array of structs. Key names are lowercase. Empty fields are treated as nulls">
hint="Преобразует query в массив структур. Имена ключей приводятся к нижнему регистру, пустые поля считаются null">
<cfargument name="Query" type="query" required="true" />
@@ -308,7 +274,7 @@
access="public"
returntype="any"
output="false"
hint="convert snake style name to camel style name">
hint="Преобразует имя в стиле snake_case в camelCase">
<cfargument name="snake" type="string" required="true" />
<cfreturn #reReplace(ARGUMENTS.snake,"_([a-z])","\u\1","ALL")#/>
</cffunction>
@@ -318,7 +284,7 @@
access="public"
returntype="any"
output="false"
hint="convert camel style name to snake style name">
hint="Преобразует имя в стиле camelCase в snake_case">
<cfargument name="snake" type="string" required="true" />
<cfreturn #reReplace(ARGUMENTS.snake,"([A-Z])","_\l\1","ALL")#/>
</cffunction>
@@ -327,7 +293,7 @@
access="public"
returntype="any"
output="true"
hint="formats Exception for display">
hint="Форматирует сообщение для вывода">
<cfargument name="message" type="string" required="true" />
<cfargument name="title" type="string" required="false" />
@@ -342,7 +308,7 @@
access="public"
returntype="any"
output="true"
hint="formats Exception for display">
hint="Форматирует исключение для вывода">
<cfargument name="ex" type="struct" required="true" />
<cfargument name="title" type="string" required="false" />
@@ -357,7 +323,7 @@
access="public"
returntype="any"
output="true"
hint="formats Bad Request Exception">
hint="Форматирует ошибку Bad Request">
<cfargument name="ex" type="struct" required="true" />
@@ -366,41 +332,6 @@
<cfreturn {type="about:blank", title="Bad Request", detail="#detail#"}/>
</cffunction>
<!---<cffunction name="wrapResultSet"
access="public"
returntype="any"
output="true"
hint="format resultset as json">
<cfargument name="qRead" type="query" required="true" />
<cfargument name="titleMap" type="struct" required="true" />
<cfargument name="startrow" type="integer" required="false" default="1" />
<cfset var resultSet=[]/>
<cfloop query=#ARGUMENTS.qRead# startRow=#ARGUMENTS.startrow#>
<cfset var rec={}/>
<cfset appendRecord(rec, "", ARGUMENTS.titleMap, ARGUMENTS.qRead, snake2camel)/>
<cfset arrayAppend(resultSet, rec)/>
</cfloop>
<cfset var out={
pageSize=
}/>
<cfcontent type="application/json"/>
<cfoutput>{
"pageSize":#pageSize#,
"page":#page#,
"orderBy":"#orderBy#",
"size":"#arrayLen(resultSet)#",
"total":"#qTotal.cnt#",
"results":#serializeJson(resultSet)#,
"queryDurationMs":#queryDurationMs#, <cfset runDurationMs=getTickCount()-request.startTickCount/>
"runDurationMs":#runDurationMs#
}</cfoutput>--->
<cffunction name="isValidX"
access="private"
returntype="boolean"
@@ -420,7 +351,7 @@
access="public"
returntype="any"
output="false"
hint="validate field of a structure, if exisits">
hint="Проверяет поле структуры, если оно существует">
<cfargument name="struct" type="struct" required=true/>
<cfargument name="name" required=true/>