做一个 WebAPI
本页把 WebAPI 最常见的查找路径压缩到一个地方：返回封包、异常处理、认证授权、Swagger 对齐、项目差异。
我现在要解决什么
- 如何统一前端返回包
{ data, code, msg, errMsg, tid }。 - 异常在哪一层处理。
- 认证授权由框架接管还是宿主显式接入。
- Swagger 如何与响应封包保持一致。
先看哪几页
最短落地路径
- 新服务：先按主题页落规范，再按 后端初始化教程 补最小骨架。
- 老项目改造：直接对照下方“示例与落地对照”里的认证和异常链做法。
最小接入步骤
- 在 MVC 过滤器注册处统一挂上
ExceptionHandlerFilter和EnvelopFilterAttribute。 - 确认认证授权到底走框架集成还是宿主显式接入，只保留一条路径。
- 对照 EnvelopMessage 的成功链路图、异常链路图和最小配置示例，检查请求最终是如何被包装的。
- 检查 Swagger 是否描述了真实的封包结构，而不是 Controller 的裸返回类型。
你应该改哪些位置
- 宿主层：过滤器注册、认证授权、Json 配置。
- 项目层：
IApiExceptionProcessor的业务异常映射。 - 文档层：Swagger 或接口说明里的响应封包结构。
- 检查层：用 WebAPI 与前端契约检查 做回归核对。
自查清单
- 成功响应是否统一返回
{ data, code, msg, errMsg, tid }。 - 统一 JSON API 的 HTTP 传输状态是否稳定为
200，并把业务分类放进code。 ModelState失败是否进入统一异常链，而不是由 Action 手工判断。[Authorize]接口是否真的经过了UseAuthentication()、UseAuthorization()，并把 challenge/forbid 统一映射到封包错误码。- 例外接口是否显式标了
IgnoreEnvelopAttribute，并在文档中说明。
示例与落地对照
niusys-webapi：ExceptionHandlerFilter + EnvelopFilterAttribute + Swagger Envelop Filters。gmandarin-backend：API 宿主启用IsIntegrateAspNetAuthentication = true。woscm：项目级异常处理器、业务错误码和 TraceId 回写。