刚学 C# 的人想写个 WebAPI 接口，往往卡在几个地方：项目建好了却不知道该往哪写业务、路由和参数怎么对应、本地跑通了部署出去调不通。这篇按「先跑通、再加工程化」的顺序给一套可照做的步骤，不讲协议原理也不讲客户端配置，只讲工程落地的那几步，并告诉你哪几步在什么情况下可以省。
刚学 C# 的人想写个 WebAPI 接口，往往卡在几个地方：项目建好了却不知道该往哪写业务，路由和参数怎么对应总是猜，本地跑通了部署出去又调不通。这篇按「先跑通、再加工程化」的顺序给一套可照做的步骤，不讲协议原理也不讲客户端配置，只讲工程落地的那几步，并告诉你哪几步在什么情况下可以省。
建议把顺序固定成四段：骨架跑通、参数与错误定型、超时与降级配最低档、日志和排查顺序固化。每一段都有能立刻验证的动作，做完一段再进下一段，别一口气全铺开。文末给了一个站内自查入口，部署前对着过一遍更稳。
第一步：把项目骨架和第一个接口跑通
用 dotnet new webapi 建最小项目，先只改一个 Controller（控制器，处理请求的类）里的方法，不要一上来就分层、加数据库、接中间件。新手最容易犯的错是骨架还没跑通就开始设计架构，结果调不通时分不清是路由问题还是自己的分层写错了。
一个接口要交代清楚四件事：HTTP 方法、路由模板、入参来源（路径、查询串还是请求体）、返回结构。缺一样调起来就会莫名 404 或 400。写完先在本机用 Swagger（接口调试页）或 curl 打一遍，确认请求能进到方法里、断点能停住，再往下写业务。
- 建最小项目执行 dotnet new webapi，不动模板结构，只保留一个控制器。
- 写一个接口在方法上标清 HTTP 方法与路由，入参来源用特性显式声明，别依赖推断。
- 本机验证用 Swagger 或 curl 发一次请求，断点能停住即为通过；停不住先查路由和启动日志。
dotnet new webapi -n DemoApi；cd DemoApi；dotnet run；curl -i http://localhost:5000/api/values第二步：参数绑定和错误返回怎么定
路径参数和查询参数适合简单值，复杂对象走请求体；类型对不上时框架会直接返回 400，不用自己写一遍类型校验。真正要自己管的是业务层面的错误：校验失败、找不到资源、没权限，这些不该混成一种返回。
- 路径参数
- 标识一条资源，放路由模板里，适合 ID 这类短值。
- 查询参数
- 筛选、分页一类可选条件，缺失时要有默认值。
- 请求体
- 复杂对象走这里，注意模型绑定失败会自动变成 400。
- 统一错误体
- 业务异常和参数异常分开，带一个可读错误码和说明。
别把 500 当成万能兜底，能判成 400、401、403 的就在接口层判掉，让调用方一眼知道是谁的问题。各状态码的适用边界可以到站内的资料库条目对照，避免凭印象写。
- 业务异常抛自定义类型，由统一中间件转成约定好的错误体结构。
- 参数异常交给框架的 400，但要在日志里记下具体哪个字段没过。
- 错误体里给一个稳定错误码，不要只给一句中文说明，前端要靠码做分支。
- 返回结构里的字段命名前后一致，别这个接口用驼峰、那个用下划线。
第三步：超时、并发与降级的最低配置
只要接口里调了外部服务——数据库、第三方接口、大模型接口——就必须设超时，连接和读取分开设。不设的默认值往往长到把线程占满，本地单测根本看不出来，只有并发上来才暴露。
并发控制先做限流和排队，再谈扩容；同一资源的修改要走乐观锁或队列，别指望靠加机器解决竞态。降级要有兜底返回值或缓存，并且让调用方能区分「降级结果」和「正常结果」，否则问题会被藏起来，排查时更费劲。
| 项目 | 最低要求 | 不做的后果 |
|---|---|---|
| 连接超时 | 给一个短值 | 连不上时线程一直等 |
| 读取超时 | 按下游耗时上限设 | 下游变慢拖垮本接口 |
| 并发限流 | 按下游能承受的量设 | 峰值把下游打挂 |
| 降级兜底 | 返回可区分的标记 | 把异常当正常结果返回 |
第四步：日志留什么、出问题按什么顺序查
每次请求至少记：时间、路径、耗时、状态码、一个请求 ID。请求 ID 要能一路透传到下游调用，否则跨服务排查时你只能靠时间戳猜，效率差很多。日志别只记成功，失败路径同样要落。
排查顺序固定成一条线，不要东看一眼西看一眼：先看接口有没有进来（日志里有没有那行），再看参数对不对，再看下游是超时还是报错，最后才看返回序列化。按这个顺序走，多数问题两三步就能定位。
- 确认请求是否进来看日志里有没有该路径的记录；没有就是网关、路由或防火墙的问题。
- 核对参数把收到的原始参数打出来，和调用方发出去的比对，看是不是绑定丢字段。
- 看下游区分超时和报错，超时查网络与超时配置，报错查下游返回体。
- 看序列化前面都正常但调用方说格式不对，检查返回对象的字段名与类型。
本地调不通、部署后调不通是两类问题：前者多半是端口和证书，后者多半是网关和防火墙，别混着查。这个分界线记住，能省掉大量来回试错的时间。
- 日志统一格式，方便按请求 ID 一条命令捞全。
- 本地与线上用同一套路由和参数写法，避免环境差异。
- 上线前把关键接口各打一遍，记录实际返回，留作基线。
- 定期回看日志里的慢请求，超时配置按实际耗时再调。
常见问题
新手要不要一开始就上分层架构和依赖注入？
可以先不分。把接口跑通、参数绑定和错误返回搞明白之后，再按 Controller、Service、Repository 拆。过早分层会让新手把时间花在理解框架而不是业务上。判断标准很简单：一个文件里的逻辑超过你能一眼看完的长度，就该拆了。
接口在本机好好的，部署到服务器就调不通，先查什么？
先确认端口有没有真正监听、防火墙和安全组有没有放行，再看反向代理有没有把路径前缀吃掉。最后才是看代码。顺序反了会在代码里找半天，结果是网关配置的问题。接口通不通可以用站内的连通性检测工具先测一遍。
什么时候该给接口加缓存或降级？
当下游调用明显比业务本身慢、或者下游不稳定会拖垮整个接口时再加。纯读、允许短暂旧数据的接口适合加缓存；写接口一般不加缓存，改成本地队列异步处理更合适。加之前先量一遍耗时分布，别凭感觉。
