直接用 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 有用得多。
