用途:本技能由在线文档《前后端共识》v1 转换而来,用于接口设计、接口评审、Controller/客户端实现和联调问题定位。命中后以下规则为强制约束,不作建议;如需最新规范或存在争议,回源核对 https://dev-platform.cisdigital.cn/elite-forge/code-specification/be-fe/v1/。
主要能力与规则:协作上使用 Torna 接口管理平台、统一 GIT 分支模型,后端先提供接口、前端确认后再实现,自测核心逻辑后再发 dev 联调。序列化统一用 Jackson,禁止 fastjson;Java 手动序列化用 cn.cisdigital.elite.forge.infra.commons.util.JsonUtils,全局 ObjectMapper 用 cn.cisdigital.elite.forge.infra.commons.serialize.ObjectMapperHolder。时间字段用毫秒时间戳,前端按时区格式化;枚举交互、存储、序列化均用 CODE,禁用 name;Long 用字符串交互,/api/** 与 /inner-api/** 统一将 Long 序列化为 String,/open-api/** 不处理;无数据字段不忽略,后端用 null,前端须兼容 null。请求仅允许 GET 和 POST,禁止 Restful;URL 用 kebab-case,禁止路径参数;每个请求独立 Param 类,非必要不继承、无冗余字段,GET 禁传 List,三个以上参数用 POST Body,分页参数统一 current、size。响应每个接口独立 VO 类,非必要不继承、无冗余字段;仅调用成功时 HTTP 状态码为 200;0 表示成功,-1 表示系统或未知异常,其他为 9 位错误码(1-3 位产品标识、4-6 位服务标识、7-9 位项目自定义且从 1 递增补零);统一响应体为 code、message、data,列表 data 为数组、单对象为对象、分页 data 含 current、size、total、records。国际化使用标准 Accept-Language,格式如 zh-CN、en-US。
使用方式:设计接口时先确定方法、URL、Param、VO、状态码、错误码、响应体、分页与国际化契约再写代码;评审时逐项指出违反项并标注章节号;Java 落地可配合 eliteforge-java-coding-spec 与 eliteforge-framework-specification,非 Java 后端也须遵守协议层规则。
限制:不自行扩展统一响应体字段,业务扩展放入 data;规范未覆盖场景标注需用户补充或外部确认。