用途:该技能用于璀璨工坊 Rust 项目的前后端接口共识,适用于接口设计、接口评审、Axum handler 与客户端实现、前后端联调问题定位。命中后相关规则为强制约束,不降级为建议;规则冲突需及时沟通确认。
主要能力:统一序列化约定,请求与响应字段使用 camelCase JSON;时间字段使用 Unix 毫秒时间戳并以 JSON number 交互,前端按业务与时区格式化;枚举协议值使用 PascalCase 且已发布值不得随意修改;Snowflake ID 等可能超出 JavaScript 安全整数范围的主键、外键、关联 ID 统一用十进制字符串,Rust DTO/VO 用 String 并在协议边界校验后转领域层 i64,时间戳、分页参数、数量等安全范围内值用 number,开放接口 /open-api/** 禁止把 i64、u64 序列化为字符串。字段无数据时属性必须出现,可空单值可为 null,集合无数据返回 [] 或 {},前端需兼容 null、[]、{}。请求使用标准 Restful 风格,GET 禁止请求体,URL 单词用 kebab-case,每个请求独立 DTO、每个接口独立 VO,禁止直接返回领域模型或数据库实体,GET 禁止传 List,三个以上参数必须用 POST Request Body,分页参数统一为 current、size。响应统一返回 Json<ApiResponse<T>> 或 Result<Json<ApiResponse<T>>, ApiError>,成功才用 HTTP 200,错误按语义映射 400、401、403、404、409、500、502 等;统一响应体为 code、message、data,错误响应 data 为空对象 {},列表 data 为数组,单对象 data 为对象,分页 data 使用 PageData<T> 含 current、size、total、records。错误码以 JSON string 返回,0 成功,-1 系统或未知异常,其他为 9 位错误码(1-3 位产品标识、4-6 位服务标识、7-9 位项目自定义且从 1 递增补零),应用错误通过 ApplicationErrorDescriptor 维护唯一 code 与 message_key。国际化使用 Accept-Language,格式如 zh-CN、en-US,en* 用英文,缺失或不支持默认中文,前后端均使用稳定业务语义的 i18n key。
使用方式:设计接口时先确定 HTTP 方法、URL、请求 DTO、VO、状态码、错误码、响应体、分页与国际化契约再写代码;评审时逐项指出违反项并标注章节号;对禁止、必须类条款给出明确结论,不自行扩展统一响应体字段,业务扩展放入 data;规范未覆盖场景标注需用户补充或外部确认。
限制:资料未提供安装命令、依赖版本、具体代码示例及平台支持范围,暂未提供。