Back to Details

docyrus-api-doctor

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Docyrus API Doctor

Docyrus API Doctor

Post-implementation checklist for Docyrus API code. Run through each applicable check after writing or modifying API logic. Fix every issue found before considering the task complete.
How to use: After implementing API logic, scan the changed code against each check below. Skip checks that don't apply to the code at hand. For detailed explanations and fix examples, read 
references/checklist-details.md
.
Docyrus API代码的实现后检查清单。在编写或修改API逻辑后逐一完成所有适用的检查。在认为任务完成之前，修复所有发现的问题。
使用方法： 实现API逻辑后，对照以下每个检查项扫描修改后的代码。跳过与当前代码无关的检查项。如需详细说明和修复示例，请阅读
references/checklist-details.md
。

BUG — Will Cause Errors

BUG — 会引发错误

#CheckWhat to look for
B1Missing 
columns
parameter		Any 
.list()
or 
.get()
call without a 
columns
property. Without it, only 
id
is returned.
B2
limit: 0
in query payload
limit
set to 
0
causes an API error. Remove 
limit
entirely or set a positive integer.
B3Child query key not in 
columns
If 
childQueries
defines key 
orders
, the string 
orders
must also appear in 
columns
.
B4Formula key not in 
columns
If 
formulas
defines key 
total
, the string 
total
must also appear in 
columns
.
B5Aggregation via 
@
column syntax		Using 
count@field
or 
sum@field
in columns. Use the 
calculations
parameter instead.
B6
distinctColumns
with 
calculations
These are mutually exclusive. Use 
calculations
for aggregation.
B7Formula 
extract
input count
extract
blocks must have exactly 1 input.
B8Formula 
not
operand count
not
blocks must have exactly 1 operand.
B9Formula 
and
/
or
operand count
and
/
or
blocks must have at least 2 operands.
B10Formula math operand countMath operations (
+
, 
-
, 
*
, 
/
, 
%
) must have at least 2 operands.
B11Formula 
case
without 
when
case
expressions must have at least 1 
when
clause.
B12Uncast literal in 
jsonb_build_object
String literals inside 
jsonb_build_object
need explicit 
"cast": "text"
— auto-cast only works inside 
concat
/
concat_ws
.
#检查项检查点
B1**缺少
columns
参数		任何未携带
columns
属性的
.list()
或
.get()
调用。如果没有该参数，接口仅会返回
id
。
B2查询负载中存在
limit: 0
limit
设置为
0
会导致API错误。请完全移除
limit
参数或者将其设置为正整数。
B3**子查询key不在
columns
中		如果
childQueries
中定义了key 
orders
，那么字符串
orders
也必须出现在
columns
中。
B4公式key不在
columns
中		如果
formulas
中定义了key 
total
，那么字符串
total
也必须出现在
columns
中。
B5通过
@
列语法实现聚合		在列中使用
count@field
或
sum@field
。请改用
calculations
参数。
B6
distinctColumns
与
calculations
共用		这两个参数互斥。聚合操作请使用
calculations
。
B7公式
extract
输入数量错误
extract
块必须恰好有1个输入。
B8公式
not
操作数数量错误
not
块必须恰好有1个操作数。
B9公式
and
/
or
操作数数量错误
and
/
or
块必须至少有2个操作数。
B10公式数学运算操作数数量错误数学运算（
+
、
-
、
*
、
/
、
%
）必须至少有2个操作数。
B11
case
表达式缺少
when
子句
case
表达式必须至少有1个
when
子句。
B12
jsonb_build_object
中存在未转型的字面量
jsonb_build_object
中的字符串字面量需要显式添加
"cast": "text" — 自动转型仅在
concat
/
concat_ws`中生效。

PERFORMANCE — Degrades Speed or Wastes Resources

性能 — 降低运行速度或浪费资源

#CheckWhat to look for
P1Unnecessary 
limit
on aggregation queries		When using 
calculations
without needing raw rows, don't send 
limit
. Aggregation returns a single grouped result naturally.
P2
fullCount
just to get a total count		If you only need the count (not the rows), use 
calculations: [{ func: 'count', field: 'id', name: 'total' }]
instead of 
fullCount: true
with row fetching.
P3Unnecessary 
columns
on calculation-only queries		When using 
calculations
and only reading aggregated values, don't send 
columns
. The calculation result is returned without needing column selection.
P4Over-fetching columnsColumns selected in 
columns
but never read in the consuming code. Only select what you render or process.
P5Large 
limit
without pagination
limit
> 200 without 
offset
/
fullCount
pagination risks slow responses and high memory usage.
P6Missing 
expand
causing N+1		Rendering relation/enum/user field 
.name
but not including that field in 
expand
. Without 
expand
, you get only the ID.
P7Fetching rows for existence checksFetching records just to check if any exist. Use 
calculations
count instead.
P8Redundant overlapping queriesMultiple queries on the same data source fetching overlapping columns that could be combined into one.
#检查项检查点
P1**聚合查询上存在不必要的
limit
参数		当使用
calculations
且不需要原始行数据时，不要传
limit
参数。聚合天然会返回单个分组结果。
P2**仅为获取总数时使用
fullCount
如果你只需要总数（不需要行数据），请使用
calculations: [{ func: 'count', field: 'id', name: 'total' }]
，而不是搭配行数据查询加
fullCount: true
。
P3**仅使用
calculations
的查询中存在不必要的
columns
参数		当使用
calculations
且仅读取聚合值时，不要传
columns
参数。无需选择列即可返回计算结果。
P4**过度拉取列数据
columns
中选择了但消费代码中从未读取的列。仅选择你需要渲染或处理的列即可。
P5**未做分页但
limit
值过大
limit
大于200且没有
offset
/
fullCount
分页逻辑会导致响应缓慢和高内存占用风险。
P6缺少
expand
参数导致N+1问题		渲染关联/枚举/用户字段的
.name
属性但未在
expand
中包含该字段。没有
expand
时你只会拿到ID。
P7拉取行数据仅用于存在性检查拉取记录仅为了检查是否存在。请改用
calculations
计数实现。
P8冗余的重复查询对同一数据源发起多次查询拉取重叠的列，这些查询可以合并为一个。

CODE QUALITY — Causes Maintenance Pain

代码质量 — 导致维护困难

#CheckWhat to look for
Q1Heavy 
as
type assertions on responses		Casting API responses with 
as Array<...>
without runtime validation. Prefer typed collection return types or add validation.
Q2Missing 
enabled
on dependent queries
useQuery
that depends on a runtime value (e.g., 
recordId
) but lacks 
enabled: !!recordId
. The query fires with 
undefined
.
Q3No error handling on mutations
.create()
, 
.update()
, 
.delete()
calls without try/catch or error feedback to the user.
Q4Missing query invalidation after mutationsAfter create/update/delete, related query keys must be invalidated so lists refresh.
Q5Serial cache invalidationsMultiple 
await queryClient.invalidateQueries(...)
in sequence. Use 
Promise.all()
for independent invalidations.
Q6Using deprecated 
expandTypes
Replace with the 
expand
parameter.
Q7Hardcoded data source pathsRaw 
client.get('/v1/apps/base/data-sources/project/items')
instead of using generated collection hooks.
Q8
distinctColumns
without 
orderBy
distinctColumns
requires 
orderBy
to define which row wins per group.
#检查项检查点
Q1对响应进行过重的
as
类型断言		没有运行时校验直接用
as Array<...>
对API响应做类型转换。优先使用类型化的集合返回类型或者添加校验逻辑。
Q2依赖型查询缺少
enabled
参数		依赖运行时值（例如
recordId
）的
useQuery
没有设置
enabled: !!recordId
。查询会以
undefined
参数发起。
Q3变更操作没有错误处理调用
.create()
、
.update()
、
.delete()
没有try/catch捕获或者没有给用户错误反馈。
Q4**变更操作后没有失效相关查询增删改操作后，必须失效相关的查询key，这样列表才会刷新。
Q5串行执行缓存失效串行执行多个
await queryClient.invalidateQueries(...)
。独立的失效操作请使用
Promise.all()
。
Q6**使用已废弃的
expandTypes
参数		请替换为
expand
参数。
Q7硬编码数据源路径直接写
client.get('/v1/apps/base/data-sources/project/items')
而不是使用生成的集合钩子。
Q8
distinctColumns
没有搭配
orderBy
distinctColumns
需要搭配
orderBy
来定义每个分组保留哪一行。

How to Run

运行方式

  1. Identify all files changed in this task that contain Docyrus API calls
  2. For each file, scan for 
    .list(
    , 
    .get(
    , 
    .create(
    , 
    .update(
    , 
    .delete(
    , 
    client.get(
    , 
    client.post(
    , 
    client.patch(
    , 
    client.delete(
  3. Check each call site against the BUG checks (B1-B12)
  4. Check query payloads against PERFORMANCE checks (P1-P8)
  5. Check surrounding code (hooks, error handling, invalidation) against CODE QUALITY checks (Q1-Q8)
  6. Fix all issues found, starting with BUG category
  1. 识别本次任务中所有包含Docyrus API调用的已修改文件
  2. 对每个文件，扫描查找
    .list(
    , 
    .get(
    , 
    .create(
    , 
    .update(
    , 
    .delete(
    , 
    client.get(
    , 
    client.post(
    , 
    client.patch(
    , 
    client.delete(
  3. 对照BUG检查项（B1-B12）检查每个调用位点
  4. 对照性能检查项（P1-P8）检查查询负载
  5. 对照代码质量检查项（Q1-Q8）检查周边代码（钩子、错误处理、失效逻辑）
  6. 修复所有发现的问题，优先修复BUG类问题

References

参考资料

  • references/checklist-details.md
     — Detailed explanation, detection pattern, and before/after fix example for every check item
  • references/checklist-details.md
     — 每个检查项的详细说明、检测模式以及修复前后的示例