agilelabs-fx-docs main framework-standards/frontend-contract.md

前端对接规范

本页定义 AgileLabs Framework 项目在前后端交互时必须稳定遵守的字段命名、返回包和时间处理约定。前端项目默认技术栈、主题模式和项目级包源，请继续阅读 前端项目规范。

适用场景

  • Web 前端、管理后台、小程序和其他直接消费 HTTP API 的客户端。
  • 前端与后端直接约定 JSON 字段结构的接口。
  • 需要长期稳定演进的前后端联调协议。

必须遵守

  • 前端消费的 JSON 字段统一使用 camelCase。
  • API 返回给前端的标准数据包固定为 { data, code, msg, errMsg, tid }。
  • 不允许同一系统中混用 camelCase、PascalCase、snake_case 作为前端默认字段风格。
  • 时间字段在前后端传输时统一使用 Unix timestamp，精度统一为毫秒 ms。
  • 禁止把 ISO 时间字符串作为前后端默认接口格式。
  • 前端展示时间前必须转换为浏览器本地时间，前端输入本地时间后发送给服务端前必须转换为 UTC 时间戳。

推荐做法

  • 在宿主层一次性配置前端接口所需的 Json 命名策略和时间转换器。
  • 让前端只感知一套稳定协议，不让页面层直接兼容多种返回包或多种时间格式。
  • 将接口联调文档、Swagger 示例、Mock 数据和真实接口保持一致。
  • 对需要兼容旧接口的页面，在前端适配层显式转换，不把混乱传播到新页面。

运作机制

  • C# 代码模型保持 PascalCase，数据库命名保持 snake_case，前端契约保持 camelCase，三者不需要也不应该强行统一成一种写法。
  • 命名转换由序列化配置、ORM 命名约定和必要的 DTO / 映射层共同承担，不由页面或控制器零散手写。
  • 框架提供 JsonNetSerializerSettings 的多种命名策略装饰器，项目需要明确选择面向前端的稳定策略并保持全局一致。
  • 返回包之所以固定，是为了让前端统一处理成功、业务错误和链路追踪，而不是为每个页面定制解析逻辑。

常见问题

  • “C# 明明是 PascalCase，为什么前端还要看 camelCase？” 因为代码风格和对外契约是两层规则。后端保持 C# 习惯，前端保持 JavaScript 生态习惯，转换由框架配置承担。
  • “能不能少返回 errMsg 或 tid？” 不建议。errMsg 和 tid 分别承担调试提示和链路追踪，不应靠前端猜测。
  • “旧接口已经是 PascalCase 怎么办？” 在兼容期可以保留，但必须在检查页中标记为偏差，并在适配层完成过渡。

相关检查

示例项目对照