MSW 3 通关教程

外观

7.1 综合场景：REST / GraphQL / WebSocket / FormData ​

本章把前面所有知识点串成完整应用场景，并指向仓库中的两个对等示例。

场景一：RESTful API 完整模拟 ​

一套博客后台 API 的典型端点（本仓库全部实现）：

方法 & 路径说明关键状态码
GET /api/users分页/搜索/角色过滤200
POST /api/users创建（需登录）201 / 401 / 409 / 422
PATCH /api/users/:id更新200 / 401 / 404 / 422
DELETE /api/users/:id删除（需 admin）204 / 401 / 403 / 409
GET /api/posts分页/作者/标签/发布过滤200
POST /api/posts标题≥4、正文≥10、tags 数组201 / 422
GET /api/posts/:id详情200 / 404

设计要点回顾：统一分页壳 {data,page,pageSize,total,totalPages}、统一错误信封 {error:{code,message}}、201 带 Location、写操作全部需要 Bearer 令牌。

场景二：GraphQL 查询与变更 ​

ts
// POST /graphql 单端点，按 operationName 分发
query ListUsers($page: Int, $pageSize: Int, $q: String)   // 分页查询
query User($id: ID!)                                      // 单条；不存在时 data.user=null + errors
mutation CreateUser($input: CreateUserInput!)             // 需 Bearer；邮箱冲突 409
mutation DeleteUser($id: ID!)                             // 需 admin；401/403 对照

与 REST 共用同一份假数据库与令牌校验 —— 协议只是外壳，业务规则不变。 直接玩：交互实验室 → GraphQL。

场景三：WebSocket 实时消息 ​

ws.link("ws://*/ws/chat") 实现的聊天室协议：

方向帧说明
server → client{type:"system", text}欢迎语、加入/离开广播
client → server任意文本广播给全部连接（开两个标签可见证）
server → client{type:"ping", time}每 5 秒心跳；client 可回 ping 收 pong
client → server"close-me"服务端以 4001 关闭（业务码示例）
client → server"error-me"服务端以 1011 关闭（内部错误示例）

另有 /ws/echo 回显链路用于调试。注意 MSW 3 客户端侧只有 open/message/close 事件，错误通过关闭码表达。

场景四：FormData 与二进制 ​

端点演示点
POST /api/uploadmultipart/form-data 解析、字段名校验（422）、回显文件元数据
GET /api/files/:id上传后按 id 查询
GET /api/download/svg · csv · png三种 Content-Type；svg/csv 带 Content-Disposition
POST /api/echo/headers回显请求头，调试用
GET /api/require-header自定义头 + Accept 协商（400/406）

两个示例工程（功能对等） ​

examples/
├── react-example/   # React 19 + TS 7 语义，useSyncExternalStore 会话/日志
└── vue-example/     # Vue 3.5 + Pinia 4 setup stores，同一套 @msw-tutorial/mocks

七个面板一一对应：① 基础拦截 ② 场景控制台 ③ CRUD 持久化 ④ 认证流程 ⑤ FormData/二进制 ⑥ GraphQL ⑦ WebSocket；右侧常驻请求检查器展示原始请求头/体、响应体与耗时。

bash
pnpm install
pnpm dev:react     # http://localhost:5173
pnpm dev:vue       # http://localhost:5174
pnpm docs:dev      # http://localhost:5175（你正在看的站点）

不想 clone 仓库？也可以在 StackBlitz（WebContainers，支持 pnpm workspace）中在线打开整个 monorepo，终端执行 pnpm install && pnpm dev:react 即可： 在 StackBlitz 中打开。 （仓库为私有访问时，需先在 StackBlitz 登录 GitHub 并完成授权。）

下载示例文件 ​

mock 场景清单（≥10 个，实际 12 类） ​

system / users / posts / auth / files / graphql / ws / external(GitHub passthrough) … 完整列表见 packages/mocks/src/handlers/，每个文件头部都有中文说明。

想不看工程、直接在页面里操作？下一页就是交互实验室。