@farris/cli 2.3.8 → 2.3.11

package/templates/mobile/mock/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  // mock 目录的独立 TS 工程：只服务于编辑器与按需类型检查（应用自身的 typecheck 不含本目录）。
+  // msw 是应用的开发期依赖（见 package.json 的 devDependencies），按常规模块解析即可。
+  "extends": "../tsconfig.json",
+  "compilerOptions": {
+    "composite": false,
+    "noEmit": true
+  },
+  "include": ["**/*.ts", "**/*.d.ts"]
+}

package/templates/mobile/package.json

@@ -34,6 +34,7 @@
     "eslint": "^8.57.0",
     "eslint-plugin-vue": "^9.23.0",
     "jsdom": "^25.0.1",
+    "msw": "^2.15.0",
     "prettier": "^3.2.5",
     "typescript": "~5.4.0",
     "vite": "^5.4.19",

package/templates/web/.gitignore.tpl

@@ -31,3 +31,4 @@ package-lock.json
 .windsurf/
 .trae/
 .opencode/
+.prototypes/

package/templates/web/mock/README.md

@@ -1,40 +1,53 @@
 # mock 目录
 
-开发期接口数据。一个领域一个文件，命名 `*.mock.ts`，默认导出路由数组：
+开发期接口数据。用 MSW 写法，库本身的用法见 MSW 官方文档。一个领域一个文件，命名 `*.mock.ts`，只导出 handler 数组：
 
 ```ts
-export default [
-  {
-    url: '/api/v1/users', // 必须与代码中的请求路径逐字一致
-    method: 'GET', // 默认 GET
-    timeout: 300, // 可选 模拟延迟毫秒
-    status: 200, // 可选 响应状态码
-    response: ({ query, params, body }) => ({
-      data: [],
-      total: 0
-    })
-  }
+import { http, HttpResponse, delay } from 'msw';
+
+export const handlers = [
+  http.get('/api/v1/users', async ({ request }) => {
+    const keyword = new URL(request.url).searchParams.get('keyword') ?? '';
+    await delay(300); // 可选：模拟延迟，单位毫秒
+    return HttpResponse.json({ data: [], total: 0 }); // 形状跟客户端出口走
+  }),
+  http.get('/api/v1/users/:id', ({ params }) => HttpResponse.json({ data: { id: params.id } })),
+  http.post('/api/v1/users', async ({ request }) => {
+    const body = await request.json();
+    return HttpResponse.json({ id: 'u-new', ...body }, { status: 201 });
+  })
 ];
 ```
 
 ## 加一条 mock 并验证
 
-1. 先在 `src/api/` 里确认请求路径（例如 `/api/v1/users`），逐字抄进 `url`。
-2. 新建或追加 `mock/<领域>.mock.ts`，按上面的形状写 `url` / `method` / `response`。
+1. 先在 `src/api/` 里确认实际请求路径（例如 `/api/v1/users`），逐字抄进 handler 路径，前缀也要带上。
+2. 新建或追加 `mock/<领域>.mock.ts`，按上面的形状写 handler；同一前缀下字面量路径写在 `:参数名` 之前。
 3. 在工程目录执行 `pnpm dev`，打开用到该接口的页面，**验证**返回的是 mock 数据。
-4. 需要联调真实后端时：`pnpm dev --no-mock`（或 `MOCK=none pnpm dev`），业务代码不改。
+4. 需要联调真实后端时执行 `pnpm dev --no-mock`（或 `MOCK=none pnpm dev`），业务代码不改。
 
-## 规则
+规则：
 
-- url 必须与代码中的请求路径逐字一致，见 `src/api/` 下的接口模块。
-- 路径参数在 url 里用 `:参数名` 表示，例如 `/api/v1/users/:id`；查询参数不写进 url，在 response 的 `query` 里读取。
-- mock 响应体必须能被工程的 HTTP 客户端正确消费，形状跟着客户端出口走。
-- 同一 url 不允许在多个 mock 文件中重复定义，重复时开发服务启动即报错。
-- mock 只用于开发期：不进构建产物，也不要在组件里散落假数据。
+- url 必须与代码实际发出的请求路径逐字一致，前缀也要带上；请求路径见 `src/api/` 下的接口模块。
+- url 只写路径，以 `/` 开头，不要写协议与主机。写 `/api/v1/users`，不要写 `http://localhost:3000/api/v1/users`；主机或端口不同时不会命中。
+- 路径参数在 url 里用 `:参数名` 表示，例如 `/api/v1/users/:id`。查询参数不写进 url，用 `new URL(request.url).searchParams` 读取。
+- 同一前缀下同时有字面量路径与 `:参数名` 路径时，字面量写在前面。MSW 取第一个匹配的 handler，`/api/v1/users/current` 排在 `/api/v1/users/:id` 后面会被 `:id` 接走。
+- 响应体必须能被工程的 HTTP 客户端正确消费，形状跟着客户端出口走。数据要有业务语义，用中文姓名、机构、单据号这类内容，不要用占位文本。
+- 关键场景要模拟：空态、错误、慢响应。错误用 `HttpResponse.json(..., { status: 500 })`；慢响应用 `delay`。
+- 目录里只放 handler 文件。共享数据或工具函数要放进 `_` 开头的文件，例如 `_data.ts`，加载时会跳过；其他文件会被当作 handler 文件加载，导出内容不是 handler 就会报错。
+- 同一路径不允许在多个 mock 文件中重复定义，重复时开发服务启动或请求即报错。
+- 文件只导出 handler 数组，写 `export const handlers = [...]` 或 `export default [...]`。不需要 `setupServer` / `setupWorker` 接线；接线由脚手架完成。
+- `msw` 已由模板放进应用 `devDependencies`，版本随工作区 catalog 统一。不要把它加到 `dependencies`，也不要在 `mock/` 之外引用它，否则构建期会报错。
+- mock 只用于开发期，不参与构建，也不要在组件里散落假数据。
 
-## 行为与开关
+行为：
 
-- 命中 mock → 返回 mock 数据。
-- 未命中 → 按 `farris.config.mjs` 的 `proxy` 配置转发真实后端。
-- 未命中且未配代理的 `/api` 路径 → 返回 404 并提示，便于排查漏配。
-- 开关：工程目录内 `pnpm dev` 默认生效；`pnpm dev --no-mock` 或 `MOCK=none pnpm dev` 进真实后端联调。
+- 命中 mock 时返回 mock 数据。
+- 未命中时按 `farris.config.mjs` 的 `proxy` 配置转发真实后端。
+- 未命中且未配代理的 `/api` 路径返回 404 并提示，便于排查漏配。
+
+开关：在工程目录执行 `pnpm dev` 默认生效；`pnpm dev --no-mock` 或 `MOCK=none pnpm dev` 进入真实后端联调。
+
+类型：本目录附带独立的 `tsconfig.json`，只服务于编辑器与按需类型检查。应用自身的 `typecheck` 不包含本目录，mock 也不参与构建。
+
+约定版本 2026-09。本文件随 `@farris/cli` 模板发布，AI 协作以本文件为准。

package/templates/web/mock/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  // mock 目录的独立 TS 工程：只服务于编辑器与按需类型检查（应用自身的 typecheck 不含本目录）。
+  // msw 是应用的开发期依赖（见 package.json 的 devDependencies），按常规模块解析即可。
+  "extends": "../tsconfig.json",
+  "compilerOptions": {
+    "composite": false,
+    "noEmit": true
+  },
+  "include": ["**/*.ts", "**/*.d.ts"]
+}

package/templates/web/package.json

@@ -34,6 +34,7 @@
     "eslint": "^8.57.0",
     "eslint-plugin-vue": "^9.23.0",
     "jsdom": "^25.0.1",
+    "msw": "^2.15.0",
     "prettier": "^3.2.5",
     "typescript": "~5.4.0",
     "vite": "^5.4.19",