第 4 章 进层：路由与请求处理
第 4 章 · 进层：路由与请求处理
章节摘要：本章跟着一次真正的业务请求进层——它带着路径与方法撞进路由，带着查询串、请求体与请求头涌向参数解析，有时还拖着一份文件字节流。路由匹配、RESTful 设计、参数校验、文件流处理，四站走完，"进层"这半程就通了。
一条主线：一个订单接口的进层之旅
第 3 章装配好的洋葱已经就位，本章主线盯住一个具体接口：POST /api/v1/orders，创建一笔订单。这个看似普通的请求会依次经过路由匹配（路径与方法怎么对上号）、RESTful 语义审查（资源怎么建模、状态码怎么选）、参数解析（query、body、headers、路径参数各自从哪来、怎么验），遇到带附件的变体时还要过文件流这一站。盯住一个接口的好处是每节学到的知识都立刻有落点——4.1 让请求找到归宿，4.2 让归宿符合语义，4.3 让输入可信，4.4 处理变体。走完本章，你写出的每个接口都能回答"我的参数从哪来、凭什么可信、错了谁负责"。
沿途站点
- 4.1 koa-router 与路由匹配——路由表的匹配规则、路径参数与命名捕获、路由级中间件（让鉴权只挂在某些路由上）、多路由器的挂载与嵌套。
- 4.2 RESTful API 设计与实现——把订单建模成资源，设计完整的资源到方法矩阵，实现一个可运行的订单 CRUD，重点放在状态码与错误语义的落地。
- 4.3 请求参数解析——四类输入（路径参数、查询串、请求体、请求头）的读取位置与信任等级，用一层校验中间件把"参数合法"变成前置事实。
- 4.4 文件上传与流式处理——multipart 请求的解析、大文件的流式转存、下载侧的流式输出，以及内存与磁盘的边界。
拐点与结论
本章的拐点在 4.3：很多团队的路由处理器里散落着 if (!query.id) throw ... 这样的零散校验，写多了才发现校验逻辑比业务逻辑还长。转折在于把"参数合法"从事中检查前移为层上的前置事实——请求穿过校验层之后，处理器面对的参数已经是可信的、规范的、带类型的。结论是：路由负责找到归宿，校验负责保证输入，处理器只写业务——三者各管一段，接口的复杂度才不会随数量线性爆炸。
一次请求的进层路径如下图。
图 4-0：进层半程的四道关卡
进层设计的四条军规
把本章的工程立场提前立在这，四条军规贯穿四节。其一，路由表即文档：资源命名、方法齐备性、鉴权挂载情况，看路由声明就能读出一半——写路由时保持这份自觉，命名与层次自然不跑偏。其二，动词不进路径：业务动作先翻译成资源与方法，实在表达不了的迁移动作才用名词化子资源（如取消订单），/deleteOrder 这类设计在本章活不过评审。其三，输入一律先验后用：校验层挡结构、业务层挡越界，处理器里不该出现裸的 if 校验。其四，字节流走流不走内存：上传下载都让数据分块流动，内存占用与文件大小脱钩，这是文件接口能在生产活着的底线。
读完你应该
- 能设计多资源、带版本前缀的路由表，正确使用路径参数、前缀与 allowedMethods；
- 能把一个业务实体建模成 RESTful 资源，写出方法矩阵并为每个操作选定状态码；
- 能实现资源到方法矩阵的完整处理器，错误语义与 2.4 节的异常体系衔接；
- 能用校验层把四类输入变成前置事实，处理器内不再出现零散的 if 校验；
- 能实现 multipart 上传的流式转存与下载的流式输出，说清内存边界怎么守。
下一章的接力
请求处理完毕，响应怎么体面地出去？下一章调转方向进入"出层"半程：状态码与响应头的最终控制、多格式响应、内容协商与静态资源缓存——那是洋葱的右半弧，也是用户真正感知到的部分。