asp.net core web api 关键点：用 controllerbase 而非 controller；必须显式标注 [fromquery]/[frombody]/[fromroute]；json 字段名需统一配置 propertynamingpolicy；cors 中间件须在 userouting 后、useendpoints 前注册。
直接用 ASP.NET Core 创建 Web API，别从“新建项目→选模板→F5运行”开始讲起——那不是教程，是向导。你真正卡住的地方，通常是路由没生效、模型绑定失败、跨域被拦、或者返回的 JSON 字段名不对。
Controller 继承 ControllerBase 而不是 Controller
如果你只需要返回 JSON（比如前端调用的纯 API），ControllerBase 更干净：它不带 View()、PartialView() 这些 MVC 专属方法，编译期就能防误用。
常见错误：手抖继承了 Controller，结果 IDE 提示 ViewBag 可用，但你根本不需要——这会悄悄增加不必要的依赖和内存开销。
- API 控制器一律用
[ApiController]特性标记 -
ControllerBase默认启用模型验证失败自动返回400 Bad Request，不用自己写if (!ModelState.IsValid) return BadRequest(); - 如果后续真要混用 View（比如管理后台页面），再改继承关系，而不是一开始贪方便选错基类
[FromQuery]、[FromBody]、[FromRoute] 必须显式声明
ASP.NET Core 不再默认猜测参数来源。不加特性，string id 会被当成 [FromQuery]，而 MyDto dto 会被当成 [FromBody]——但这个“默认规则”极易被忽略，导致 POST 请求体为空、GET 参数收不到。
真实踩坑场景：前端发 POST /api/users 带 JSON，后端方法写成
public IActionResult Create(User user)，结果
user 始终为 null，因为没加 [FromBody]。
- 查询参数（URL ?a=1&b=2）→ 用
[FromQuery] - JSON/XML 请求体 → 用
[FromBody]（且一个方法最多一个） - 路由段值（如
/api/users/{id}）→ 用[FromRoute]或直接写在路由模板里 - 表单数据（
application/x-www-form-urlencoded）→ 用[FromForm]，别指望[FromBody]能解析它
返回 JSON 时字段名大小写不一致？检查 JsonSerializerOptions.PropertyNamingPolicy
默认情况下，.NET 6+ 使用 JsonSerializerOptions.PropertyNamingPolicy = JsonNamingPolicy.CamelCase，所以 C# 类的 UserName 会序列化成 userName。但如果你手动 new JsonSerializerOptions() 却没设这个，或用了旧版 Newtonsoft.Json（JsonProperty 特性没生效），字段名就可能全大写或全小写，前端解包失败。
典型错误现象：Postman 看响应是 {"UserName":"abc"}，但 Axios 收到的是 undefined，因为 JS 解构写了 const { userName } = res.data。
- 全局配置（推荐）：在
Program.cs里加builder.Services.ConfigureHttpJsonOptions(options => { options.SerializerOptions.PropertyNamingPolicy = JsonNamingPolicy.CamelCase; }); - 局部覆盖：用
JsonResult构造时传入自定义JsonSerializerOptions - 别混用 System.Text.Json 和 Newtonsoft.Json 的配置——它们互不识别对方的特性
CORS 报错 “No 'Access-Control-Allow-Origin' header”？别只在控制器上加 [EnableCors]
很多人加了 [EnableCors("MyPolicy")] 还是 403，因为中间件顺序错了。CORS 中间件必须在 UseRouting() 之后、UseEndpoints() 之前注册，否则预检请求（OPTIONS）根本进不到策略匹配环节。
更隐蔽的问题：策略名拼错、没允许凭据（AllowCredentials()）、或者前端带了 Authorization 头但策略里没显式 WithHeaders("Authorization")。
- 在
Program.cs配置策略：builder.Services.AddCors(options => { options.AddPolicy("MyPolicy", policy => policy.WithOrigins("https://localhost:5173").AllowAnyMethod().AllowAnyHeader().AllowCredentials()); }); - 中间件顺序必须是：
UseRouting()→UseCors()→UseAuthentication()→UseAuthorization()→UseEndpoints() - 开发阶段可先用
AllowAnyOrigin()排查，但上线前必须锁定具体域名
Web API 的难点不在“怎么写第一个接口”，而在“为什么这个接口在本地能跑，部署后就 404 或 500”。路由模板拼写、模型绑定源声明、JSON 序列化策略、CORS 中间件位置——这些地方一错，错误信息往往不指向根因。动手前先确认这四点，比反复重启 IIS 或重写 Controller 有用得多。
