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