2
0
Эх сурвалжийг харах

docs: 在编码标准中添加hono/testing testClient规范引用

在编码标准文档中添加新的"RPC API测试规范(hono/testing)"章节:
- 添加路径到属性映射规则说明
- 添加模块内路由规范说明
- 包含正确示例和常见错误避免
- 在相关文档章节中添加testClient规范文档链接

版本更新:3.0 → 3.1

🤖 Generated with [Claude Code](https://claude.com/claude-code)
via [Happy](https://happy.engineering)

Co-Authored-By: Claude <noreply@anthropic.com>
Co-Authored-By: Happy <yesreply@happy.engineering>
yourname 2 долоо хоног өмнө
parent
commit
fff19784f9

+ 68 - 0
docs/architecture/coding-standards.md

@@ -3,6 +3,7 @@
 ## 版本信息
 | 版本 | 日期 | 描述 | 作者 |
 |------|------|------|------|
+| 3.1 | 2026-01-03 | 添加hono/testing testClient调用规范引用 | James (Claude Code) |
 | 3.0 | 2025-12-26 | 拆分测试策略到独立文档,保留编码标准 | James (Claude Code) |
 | 2.5 | 2025-12-26 | 添加Mini UI包开发规范章节 | Bob (Scrum Master) |
 | 2.4 | 2025-09-20 | 与主架构文档版本一致 | Winston |
@@ -271,6 +272,72 @@ export const ChannelSchema = z.object({
 - 认证模块:`packages/core-module/auth-module`
 - 用户模块:`packages/core-module/user-module`
 
+### RPC API测试规范(hono/testing)
+使用 `hono/testing` 的 `testClient` 测试API路由时,**必须**参考并遵循[hono/testing testClient调用规范](./hono-testing-testclient-standards.md),该规范基于故事010.003(修复路由路径规范问题)的经验总结。
+
+**关键检查点**:
+
+#### 1. 路径到属性映射规则
+- **路径分隔符 `/` 转换为嵌套对象**: `/users/:id` → `client.users[':id']`
+- **路径参数 `:param` 转换为 `[':param']` 索引**: 不能用点号访问
+- **中线 `-` (kebab-case) 必须使用方括号**: `/admin-users` → `client['admin-users']`
+
+**正确示例**:
+```typescript
+// 路由定义: path: '/'
+const response = await client.$get({
+  query: { page: 1 }
+});
+
+// 路由定义: path: '/:id'
+const response = await client[':id'].$get({
+  param: { id: 123 }
+});
+
+// 路由定义: path: '/admin-users'
+const response = await client['admin-users'].$get();
+
+// 路由定义: path: '/unified-advertisements/:id'
+const response = await client['unified-advertisements'][':id'].$put({
+  param: { id: 123 },
+  json: updateData
+});
+```
+
+#### 2. 模块内路由规范
+- **模块内使用相对路径**: `path: '/'` 或 `path: '/:id'`
+- **Server注册时添加前缀**: `.route('/api/v1/xxx', routes)`
+
+**正确示例**:
+```typescript
+// ✅ 正确: 模块内使用相对路径
+const listRoute = createRoute({
+  method: 'get',
+  path: '/',  // 而非 '/api/v1/admin/users'
+  middleware: [authMiddleware],
+  // ...
+});
+
+// packages/server/src/index.ts
+// ✅ 正确: Server包注册时添加完整前缀
+app.route('/api/v1/admin/unified-advertisements', unifiedAdvertisementAdminRoutes);
+
+// 测试时使用模块的相对路径
+const adminClient = testClient(unifiedAdvertisementAdminRoutes);
+const response = await adminClient.$get();
+```
+
+**常见错误避免**:
+- ❌ 不要使用完整路径字符串:`client['/api/v1/users'].$get()`
+- ❌ 不要忘记使用 `:id` 索引:`client.users[id].$get()` → `client.users[':id'].$get()`
+- ❌ 中线路径不要用点号访问:`client.admin-users.$get()` → `client['admin-users'].$get()`
+- ❌ 嵌套路由不要用斜杠分隔:`client['admin/users/:id'].$get()` → `client.admin.users[':id'].$get()`
+- ❌ 模块内路由不要包含完整路径:`path: '/api/v1/admin/users'` → `path: '/'`
+
+**参考实现**:
+- 统一广告模块测试:`packages/unified-advertisements-module/tests/integration/`
+- 认证模块测试:`packages/core-module-mt/auth-module-mt/tests/`
+
 ## 类型安全
 
 ### TypeScript配置
@@ -460,6 +527,7 @@ export { userSchema } from './schemas';
 - [UI包开发规范](./ui-package-standards.md)
 - [Mini UI包开发规范](./mini-ui-package-standards.md)
 - [后端模块包开发规范](./backend-module-package-standards.md)
+- [hono/testing testClient调用规范](./hono-testing-testclient-standards.md)
 - [API设计规范](./api-design-integration.md)
 
 ---