WebAPI 规范

本页定义 AgileLabs Framework 项目的 WebAPI 正式规则，包括统一返回封包、异常链、认证授权和文档对齐要求。

适用场景

ApiController 控制器。
提供给前端、第三方系统或内部服务的 HTTP API。
需要统一返回结构、错误处理和 Swagger 文档的项目。

必须遵守

标准 API 响应默认使用统一封包，不混用裸对象和局部自定义 JSON。
API 对前端返回的默认协议固定为 { data, code, msg, errMsg, tid }。
正常返回和业务错误都必须经过统一异常链或统一封包链处理，不在每个 Action 手工拼装结果。
模型验证错误、业务错误和系统错误必须走统一处理策略，不把数据库异常或系统堆栈直接暴露给前端。
认证授权接入必须统一，要么由框架集成，要么由宿主显式接入，不允许半自动半手工混用。
Swagger 或其他接口文档必须与真实响应结构保持一致。

推荐做法

使用统一过滤器和项目级异常处理器承接所有成功响应与错误映射。
在宿主阶段统一配置 Json 序列化和时间转换，而不是在 Action 内逐个处理字段。
对开放接口、回调接口、匿名接口单独标明访问策略和返回协议。
将 tid 作为请求追踪和问题排查的稳定字段回传给前端。

运作机制

WebAPI 的统一性来自过滤器、异常处理器、Json 配置和宿主接入顺序的组合，而不是单个控制器的手工约定。
项目可以像 woscm 一样扩展自己的封包对象，但字段语义仍要稳定映射到 data、code、msg、errMsg、tid 这一组前端契约。
如果项目继续使用 EnvelopMessage 或自定义信封对象，必须保证对前端暴露的文档和实际字段结构一致。

常见问题

“现有接口已经返回裸对象，能否继续保留？” 不能作为默认规则。兼容期可以保留，但必须标记为偏差并制定收敛计划。
“错误返回能否只返回 msg，不带 code 和 tid？” 不建议。这样会让前端无法稳定处理错误分类和问题追踪。
“项目用了自定义封包类，是不是就不算合规？” 不一定。关键是对外协议是否稳定、字段语义是否与规范一致。

相关检查

示例项目对照

niusys-webapi：统一异常链、统一 Json 配置、Swagger 封包对齐。
woscm：项目级异常处理器、业务错误码和 TraceId 回写。
WebAPI 主题：主题视角的补充说明。