SuperAPI AI 工具集

cc-api-design-safety

编程与开发

查看项目

更新于 10-15 21:11

技能介绍

用途:在设计与修改 REST API 响应结构、处理 API 返回值,或生成 Excel/CSV/PDF/对账文件等下游产物时触发,防止设计缺陷导致字段错位、类型歧义,以及产物关键字段缺失但静默成功。

主要能力:覆盖六类陷阱。一是泛型方法重载歧义,String 返回可能匹配到 success(String message) 而非 success(T data),可用明确 message 参数、显式泛型或包装 DTO 规避。二是响应字段语义不清,规范 code 为业务状态码、message 为用户可读提示、data 为业务数据、timestamp 为 ISO 8601 时间。三是空值处理不一致,单对象不存在返回 data:null,列表为空返回 [],分页为空返回 {list:[],total:0}。四是 HTTP 状态码与业务状态码混淆,业务失败返回 HTTP 200 加业务 code,仅代码异常返回 500。五是生成下游产物前缺乏完整性校验,需按业务字段、依赖配置、外键关联三层次列全必填项,依据下游消费方文档判断,缺失时抛含业务 ID 的业务错误而非空值兜底。六是业务错用框架异常导致全部变成 500,业务可预期错误用 BusinessException,代码 bug 与系统故障让框架异常冒泡。

使用方式:作为技能在相应场景触发,按检查清单逐项核对返回值设计、状态码设计、前后端协议与产物完整性。多语言实现示例见 references/multi-lang-examples.md。

适用场景:Java Spring Boot、Go Gin/Echo、Node.js Express/Koa、Python FastAPI/Flask 的 REST API 设计与评审。

限制:资料未提供安装命令、收费与平台信息。