|
|
@@ -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)
|
|
|
|
|
|
---
|