فهرست منبع

docs: 更新Hono RPC Client规范文档,明确hc与testClient共享相同规则

主要更新:
- 标题从"hono/testing testClient调用规范"改为"Hono RPC Client调用规范"
- 概述中明确规范同时适用于testClient和hc
- 新增"5. 前端 RPC Client (hc) 使用"章节
- 说明hc调用路径与testClient完全一致
- 更新文档状态说明覆盖范围

版本更新:1.1 → 1.2

🤖 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 هفته پیش
والد
کامیت
6fe4e39054
1فایلهای تغییر یافته به همراه57 افزوده شده و 4 حذف شده
  1. 57 4
      docs/architecture/hono-testing-testclient-standards.md

+ 57 - 4
docs/architecture/hono-testing-testclient-standards.md

@@ -1,18 +1,27 @@
-# hono/testing testClient 调用规范
+# Hono RPC Client 调用规范
 
 ## 版本信息
 | 版本 | 日期 | 描述 | 作者 |
 |------|------|------|------|
 | 1.0 | 2026-01-03 | 初始版本,基于故事010.003修复经验总结 | James (Claude Code) |
 | 1.1 | 2026-01-03 | 添加中线(kebab-case)路由规范 | James (Claude Code) |
+| 1.2 | 2026-01-03 | 明确规范同样适用于前端RPC client (hc) | James (Claude Code) |
 
 ## 概述
 
-本文档定义了使用 `hono/testing` 的 `testClient` 测试API路由时的正确调用方式,避免常见的调用错误。
+本文档定义了使用 Hono RPC 客户端时的正确调用方式,包括:
+- **测试环境**: `hono/testing` 的 `testClient` - 用于集成测试
+- **生产环境**: `@hono/rpc` 的 `hc` - 用于前端 RPC 调用
+
+两者的路径映射规则完全一致,本文档的规范适用于所有 Hono RPC 客户端。
 
 ## 基本原理
 
-`testClient` 会根据Hono路由的路径结构自动生成类型安全的客户端对象。关键是理解路径到属性的映射规则。
+Hono RPC 客户端(包括 `testClient` 和 `hc`)会根据路由的路径结构自动生成类型安全的客户端对象。关键是理解路径到属性的映射规则。
+
+**所有 Hono RPC 客户端共享相同的路径映射规则**,无论是:
+- 后端测试使用的 `testClient`(来自 `hono/testing`)
+- 前端调用使用的 `hc`(来自 `@hono/rpc`)
 
 ### 核心映射规则
 
@@ -156,6 +165,46 @@ app.openapi(route, handler);
 const response = await client.admin['unified-advertisement-types'].$get();
 ```
 
+### 5. 前端 RPC Client (hc) 使用
+
+**重要**: 前端使用 `hc` 创建的 RPC 客户端与 `testClient` 使用**完全相同的路径映射规则**。
+
+```typescript
+// 前端 API 客户端创建
+import { hc } from 'hono/client';
+import type { ApiRoutes } from '@d8d/server';
+
+export const apiClient = hc<ApiRoutes>('/api/v1');
+
+// 路由定义: path: '/' (在 server 包注册为 '/api/v1/admin/unified-advertisements')
+const response = await apiClient.admin['unified-advertisements'].$get({
+  query: { page: 1, pageSize: 10 }
+});
+
+// 路由定义: path: '/:id'
+const response = await apiClient.admin['unified-advertisements'][':id'].$put({
+  param: { id: 123 },
+  json: updateData
+});
+```
+
+**关键点**:
+1. **hc 调用路径与 testClient 完全一致**: 如果测试用 `adminClient.$get()`,前端也用 `apiClient.admin.xxx.$get()`
+2. **不需要重复前缀**: hc 已经配置了 baseURL (`/api/v1`),调用时不需要再包含
+3. **类型安全**: TypeScript 会自动推断正确的路径和方法
+
+**错误示例**:
+```typescript
+// ❌ 错误: 重复包含 /api/v1 前缀
+const response = await apiClient['/api/v1/admin/unified-advertisements'].$get();
+
+// ❌ 错误: 中线路径用点号访问
+const response = await apiClient.admin.unified-advertisements.$get();
+
+// ✅ 正确: 使用方括号访问中线路径
+const response = await apiClient.admin['unified-advertisements'].$get();
+```
+
 ## 常见错误 ❌
 
 ### 错误1: 使用完整路径字符串
@@ -364,9 +413,13 @@ await client.$get()  // path: '/'  →  .$get()
 
 - [后端模块包开发规范](./backend-module-package-standards.md) - 路由定义规范
 - [后端模块包测试规范](./backend-module-testing-standards.md) - 测试框架和集成测试
+- [编码标准](./coding-standards.md) - RPC API测试规范章节
 
 ---
 
 **文档状态**: 正式版
 **创建原因**: 故事010.003修复过程中发现缺乏testClient调用规范
-**适用范围**: 所有使用 hono/testing 的后端模块测试
+**适用范围**: 所有使用 Hono RPC 客户端的地方(testClient 和 hc)
+**覆盖范围**:
+- 后端集成测试 (`hono/testing` 的 `testClient`)
+- 前端 UI 包 RPC 调用 (`@hono/rpc` 的 `hc`)