docyrus-api-doctor

Docyrus API 诊断工具

Docyrus API 代码的实现后检查清单。编写或修改 API 逻辑后，请逐项执行所有适用的检查。完成任务前，请修复发现的所有问题。

使用方法： 实现 API 逻辑后，对照以下各项检查已更改的代码。跳过不适用于当前代码的检查。如需查看详细说明和修复示例，请阅读 references/checklist-details.md。

---

BUG — 将导致错误

#	检查项	检查内容
B1	缺少 columns 参数	任何未包含 columns 属性的 .list() 或 .get() 调用。若不指定该属性，只会返回 id。
B2	查询负载中的 limit: 0	将 limit 设为 0 会导致 API 错误。请完全移除 limit，或将其设为正整数。
B3	子查询键未包含在 columns 中	如果 childQueries 定义了键 orders，则字符串 orders 也必须出现在 columns 中。
B4	公式键未包含在 columns 中	如果 formulas 定义了键 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 — 降低速度或浪费资源

#	检查项	检查内容
P1	聚合查询中不必要的 limit	使用 calculations 且不需要原始行时，不要发送 limit。聚合会自然返回单个分组结果。
P2	仅为获取总数而使用 fullCount	如果只需要计数（而不需要行），请使用 calculations: [{ func: 'count', field: 'id', name: 'total' }]，而不是结合行获取使用 fullCount: true。
P3	仅用于计算的查询中不必要的 columns	使用 calculations 且只读取聚合值时，不要发送 columns。无需选择列也会返回计算结果。
P4	获取过多列	columns 中选取的列未被使用代码读取。只选择需要呈现或处理的列。
P5	使用较大的 limit 但未分页	未使用 offset/fullCount 分页时，limit > 200 可能导致响应缓慢和内存占用过高。
P6	缺少 expand 导致 N+1 查询	呈现关联/枚举/用户字段的 .name，却未在 expand 中包含该字段。若不使用 expand，只会得到 ID。
P7	为检查是否存在记录而获取行	仅为检查是否存在记录而获取记录。请改用 calculations 计数。
P8	重复且重叠的查询	对同一数据源执行多个查询，获取重叠的列，而这些查询本可合并为一个。

代码质量 — 增加维护负担

#	检查项	检查内容
Q1	对响应大量使用 as 类型断言	使用 as Array<...> 转换 API 响应，却不进行运行时验证。优先使用带类型的集合返回类型，或添加验证。
Q2	依赖查询缺少 enabled	useQuery 依赖运行时值（例如 recordId），但缺少 enabled: !!recordId。查询会在值为 undefined 时触发。
Q3	变更操作缺少错误处理	调用 .create()、.update()、.delete() 时没有 try/catch，也没有向用户反馈错误。
Q4	变更后缺少查询失效处理	创建/更新/删除后，必须使相关查询键失效，以便刷新列表。
Q5	依次执行缓存失效操作	多个 await queryClient.invalidateQueries(...) 按顺序执行。对于互不依赖的失效操作，请使用 Promise.all()。
Q6	使用已弃用的 expandTypes	替换为 expand 参数。
Q7	数据源路径硬编码	使用原始的 client.get('/v1/apps/base/data-sources/project/items')，而不是使用生成的集合钩子。
Q8	distinctColumns 未搭配 orderBy	distinctColumns 需要 orderBy 来指定每个分组中保留哪一行。

---

如何运行

1. 找出本任务中所有包含 Docyrus API 调用的已更改文件
2. 对每个文件，检查 .list(、.get(、.create(、.update(、.delete(、client.get(、client.post(、client.patch(、client.delete(
3. 根据 BUG 检查项（B1-B12）检查每个调用位置
4. 根据 PERFORMANCE 检查项（P1-P8）检查查询负载
5. 根据 CODE QUALITY 检查项（Q1-Q8）检查周边代码（钩子、错误处理、失效处理）
6. 修复发现的所有问题，从 BUG 类别开始

参考资料

• references/checklist-details.md — 每项检查的详细说明、检测模式以及修复前后的示例