从注释生成数据字典时，怎么让 AI 写的外键说明跟 DDL 约束对得上
数据库注释与DDL对不上的根本原因是AI输入中缺少约束信息。解决方法是把完整DDL和表注释拼进同一上下文，要求AI逐条标注约束名和引用目标，并单独列出注释提到但DDL未约束的字段。生成后让AI写校验SQL查询information_schema，与实际约束逐条diff。批量处理时按外键依赖分块，每组15-20张表，确保引用方和被引用方同块。DDL无外键时，用“逻辑关联”与“物理外键”区分标注，避免误导。
标签: #接口文档
共 4 篇文章
写接口文档时，我把分页、排序、筛选参数声明复用了，结果每个接口都长得差不多，那差异化配置到底加在哪里
接口文档的复用困境源于混淆了参数声明与参数约束。解决之道在于将接口契约分为两层：结构层定义参数名称、类型等通用格式，实现复用；约束层则针对每个接口，明确具体的取值范围、白名单和业务规则，实现差异化。通过OpenAPI的`enum`、独立schema或文档中的专属约束表格，可清晰传达每个接口的独特限制，避免文档流于形式。
团队协作时接口文档老打架，试试这样合并和消解冲突
从单体 OpenAPI 文件迁移到多文件结构，是解决接口文档冲突的根本方法。通过按模块拆分规范文件，并利用构建命令拼装完整文档，可将冲突率降低 90% 以上。核心操作包括：将路径、模式等定义拆分为独立文件，用 `$ref` 在入口文件中组装，并借助 Redocly CLI 进行构建与校验。对于同一模块的并发修改，可进一步按 HTTP 方法拆分文件。若冲突发生，使用 Git 的 `union` 合并策略和编辑器插件能高效解决。
用 TypeScript 类型做接口文档，怎么让它跟后端返回保持同步
解决前后端接口类型不一致的核心方案：将 TypeScript 类型定义作为唯一真相来源，通过工具链实现自动化校验。具体做法是用 ts-json-schema-generator 将类型编译为 JSON Schema，再在 CI 中用 Ajv 校验实际响应数据。也可从后端代码直接生成前端类型，或用 OpenAPI 作为中间契约，配合 openapi-diff 检测破坏性变更。针对泛型、联合类型等复杂场景需注意工具版本和配置优化。