用途:约束璀璨工坊Java项目前后端接口共识,用于接口设计、接口评审、Controller/客户端实现和联调问题定位。命中本技能后规则为强制约束,冲突时需沟通确认。
主要能力与关键规则:序列化统一用Jackson,禁用fastjson;手动序列化用cn.cisdigital.elite.forge.infra.commons.util.JsonUtils,全局ObjectMapper用cn.cisdigital.elite.forge.infra.commons.serialize.ObjectMapperHolder。时间字段用毫秒时间戳,前端按业务和时区格式化。枚举交互、存储、序列化统一用CODE,禁用name。Long字段以字符串交互防止JS精度丢失;/api/**与/inner-api/**统一将Long序列化为String,/open-api/**使用不同ObjectMapper,不做Long转String。JSON不忽略无数据字段,后端用null表示不存在,前端必须兼容null。
请求:仅允许GET和POST,禁用Restful;URL用kebab-case,禁止路径参数;每接口独立Param类,禁止跨接口复用、非必要继承和冗余字段;GET禁止传List;三个以上参数用POST Request Body并控制大小、关注Spring/Tomcat/Nginx限制;分页参数统一为current、size。
响应:每接口独立VO类,禁止复用、非必要继承和冗余字段;仅调用成功HTTP状态码为200;成功失败用不同错误码,符合服务状态码规范,0成功,-1系统或未知异常,其他为9位错误码(1-3位产品标识,4-6位服务标识,7-9位项目自定义,从1递增、高位补0)。统一响应体为code、message、data;列表data为数组,单对象data为对象,分页data含current、size、total、records。不自行扩展响应体字段,业务扩展放入data。
国际化:用标准Accept-Language切换语言,格式为<语言代码>-<国家或地区代码>,如zh-CN、en-US。
限制:设计或评审需显式应用规范并标注章节号;规范未覆盖场景标注需用户补充或外部确认。具体安装命令与版本等信息暂未提供。