WebAPI 规范

本页定义 AgileLabs Framework 项目的 WebAPI 正式规则，包括统一返回封包、异常链、认证授权和文档对齐要求。后端在 CI/CD 中的 publish、镜像和部署边界，请继续阅读 CI/CD 规范。

适用场景

标准 API 响应默认使用统一封包，不混用裸对象和局部自定义 JSON。
API 对前端返回的默认协议固定为 { data, code, msg, errMsg, tid }。
只要 /api/* 下走统一封包的 JSON API 请求已经到达应用程序层并且仍可写回响应，HTTP 状态码一律返回 200。
正常返回和业务错误都必须经过统一异常链或统一封包链处理，不在每个 Action 手工拼装结果。
/api/* 下的 JSON WebAPI action 返回签名只能是具体 DTO、集合 DTO，或无业务返回体的 Task。
/api/* 下的 JSON WebAPI action 不得使用 IActionResult 或 ActionResult<T> 作为默认返回签名。
模型验证错误、业务错误和系统错误必须走统一处理策略，不把数据库异常或系统堆栈直接暴露给前端。
认证授权接入必须统一，要么由框架集成，要么由宿主显式接入，不允许半自动半手工混用。
Swagger 或其他接口文档必须与真实响应结构保持一致。

本节只适用于 /api/* 下的 JSON WebAPI controller。
HTML 页面、文件下载、health、SignalR hub、/api/internal/* 和最小 API 端点不套用本规则。
查询或普通成功接口应直接返回具体 DTO、IReadOnlyList<TDto>、分页 DTO 等具体模型。
无业务返回体接口应返回 Task，不使用 string.Empty、匿名对象或其他占位返回值描述空成功。
IActionResult 和 ActionResult<T> 都属于不合规写法，因为它们会掩盖 action 的真实业务模型。
即使 Action 内部设置了 201、202 或其他应用层状态码，只要接口属于统一 JSON API，最终对外传输状态码仍应被统一收口为 200，业务分类统一落在 envelope 的 code 上。
Swagger 必须能在 envelope 的 data 字段下看到真实 DTO，不能因为 action 返回签名过于泛化而退化成无类型 object。
controller 不手工拼 { data, code, msg, errMsg, tid }，统一封包和统一错误映射继续由过滤器、异常处理器和宿主配置负责。
若项目约定空成功响应仍需保留 envelope，则由统一封包链生成无业务数据的成功包，action 签名仍应保持 Task。

WebAPI 的统一性来自过滤器、异常处理器、Json 配置和宿主接入顺序的组合，而不是单个控制器的手工约定。
控制器签名负责向编译器和 Swagger 暴露真实业务模型，统一封包链负责把该模型包装成前端契约要求的 { data, code, msg, errMsg, tid }，并把 HTTP 传输状态统一收口为 200。
项目可以像 woscm 一样扩展自己的封包对象，但字段语义仍要稳定映射到 data、code、msg、errMsg、tid 这一组前端契约。
如果项目继续使用 EnvelopMessage 或自定义信封对象，必须保证对前端暴露的文档和实际字段结构一致。

“现有接口已经返回裸对象，能否继续保留？” 不能作为默认规则。兼容期可以保留，但必须标记为偏差并制定收敛计划。
“为了兼容多种状态码，能不能统一写成 ActionResult<T> 或 IActionResult？” 不能作为默认规则。统一 JSON API 对外只承诺 200，业务分类看 envelope 的 code；action 签名仍要保留具体 DTO 或 Task。
“错误返回能否只返回 msg，不带 code 和 tid？” 不建议。这样会让前端无法稳定处理错误分类和问题追踪。
“项目用了自定义封包类，是不是就不算合规？” 不一定。关键是对外协议是否稳定、字段语义是否与规范一致。