|
@@ -1,33 +1,54 @@
|
|
|
-# 编码标准和测试策略
|
|
|
|
|
|
|
+# 编码标准
|
|
|
|
|
|
|
|
## 版本信息
|
|
## 版本信息
|
|
|
| 版本 | 日期 | 描述 | 作者 |
|
|
| 版本 | 日期 | 描述 | 作者 |
|
|
|
|------|------|------|------|
|
|
|------|------|------|------|
|
|
|
|
|
+| 2.6 | 2025-12-15 | 移除测试策略内容,更新RPC客户端最佳实践,与测试策略文档保持一致 | James |
|
|
|
| 2.5 | 2025-12-12 | 修正测试目录描述,从 `__tests__` 更新为 `tests` | Bob (Scrum Master) |
|
|
| 2.5 | 2025-12-12 | 修正测试目录描述,从 `__tests__` 更新为 `tests` | Bob (Scrum Master) |
|
|
|
| 2.4 | 2025-09-20 | 与主架构文档版本一致 | Winston |
|
|
| 2.4 | 2025-09-20 | 与主架构文档版本一致 | Winston |
|
|
|
|
|
|
|
|
## 现有标准合规性
|
|
## 现有标准合规性
|
|
|
- **代码风格**: TypeScript严格模式,一致的缩进和命名
|
|
- **代码风格**: TypeScript严格模式,一致的缩进和命名
|
|
|
- **linting规则**: 已配置ESLint,支持TypeScript和React
|
|
- **linting规则**: 已配置ESLint,支持TypeScript和React
|
|
|
-- **测试模式**: 完整的测试框架已配置(Vitest + Testing Library + Playwright)
|
|
|
|
|
-- **文档风格**: 代码注释良好,测试策略文档完整
|
|
|
|
|
|
|
+- **文档风格**: 代码注释良好,架构文档完整
|
|
|
|
|
+- **测试策略**: 独立文档 `testing-strategy.md` 包含完整的测试规范和API模拟策略
|
|
|
|
|
|
|
|
-## 增强特定标准
|
|
|
|
|
-- **测试框架**: 使用Vitest + Testing Library + hono/testing + Playwright
|
|
|
|
|
-- **测试位置**: `tests` 文件夹与源码并列(例如:`packages/goods-module-mt/tests/` 与 `packages/goods-module-mt/src/` 并列)
|
|
|
|
|
-- **覆盖率目标**: 核心业务逻辑 > 80%
|
|
|
|
|
-- **测试类型**: 单元测试、集成测试、E2E测试
|
|
|
|
|
|
|
+## 架构原则
|
|
|
|
|
+- **模块化设计**: 基于monorepo的模块化架构,支持按需安装
|
|
|
|
|
+- **类型安全**: 全面使用TypeScript,确保编译时类型检查
|
|
|
|
|
+- **依赖注入**: 通过客户端管理器模式实现依赖注入,便于测试和替换
|
|
|
|
|
+- **关注点分离**: 业务逻辑、数据访问、UI呈现分层清晰
|
|
|
|
|
+- **可扩展性**: 支持单租户和多租户部署模式
|
|
|
|
|
|
|
|
-## 关键集成规则
|
|
|
|
|
-- **现有API兼容性**: 确保测试不破坏现有API契约
|
|
|
|
|
-- **数据库集成**: 使用测试数据库,避免污染生产数据
|
|
|
|
|
-- **错误处理**: 测试各种错误场景和边界条件
|
|
|
|
|
-- **日志一致性**: 测试日志格式和错误信息
|
|
|
|
|
|
|
+## 关键编码规范
|
|
|
|
|
+- **命名约定**: 使用camelCase(变量、函数)、PascalCase(类、接口)、kebab-case(文件、目录)
|
|
|
|
|
+- **代码组织**: 遵循功能分组原则,相关代码放在同一目录
|
|
|
|
|
+- **错误处理**: 统一使用异常处理,避免静默失败
|
|
|
|
|
+- **日志记录**: 结构化日志,包含上下文信息和级别
|
|
|
|
|
+- **配置管理**: 环境变量和配置文件分离,支持不同环境配置
|
|
|
|
|
+- **安全实践**: 输入验证、输出编码、最小权限原则
|
|
|
|
|
|
|
|
## RPC客户端架构最佳实践
|
|
## RPC客户端架构最佳实践
|
|
|
-- **单例模式**: 使用单例模式的客户端管理器确保全局唯一的客户端实例
|
|
|
|
|
-- **延迟初始化**: 客户端应在首次使用时初始化,避免过早创建
|
|
|
|
|
-- **类型安全**: 使用Hono的InferRequestType和InferResponseType确保类型一致性
|
|
|
|
|
-- **组件调用规范**: 在组件中应使用`clientManager.get().api.$method`而非直接使用导出的客户端实例
|
|
|
|
|
-- **测试Mock**: 在测试中正确mock客户端管理器的get()方法调用链
|
|
|
|
|
-- **架构一致性**: 确保所有API调用都通过客户端管理器获取实例,保持架构一致性
|
|
|
|
|
|
|
+
|
|
|
|
|
+### 客户端管理器模式
|
|
|
|
|
+- **单例模式**: 每个UI包使用单例模式的客户端管理器(如`AdvertisementClientManager`、`UserClientManager`)确保全局唯一的客户端实例
|
|
|
|
|
+- **延迟初始化**: 客户端应在首次使用时初始化,避免过早创建,通过`get()`方法实现懒加载
|
|
|
|
|
+- **统一基础**: 所有客户端管理器使用`@d8d/shared-ui-components`包中的`rpcClient`函数创建Hono RPC客户端
|
|
|
|
|
+- **类型安全**: 使用Hono的InferRequestType和InferResponseType确保API调用的类型一致性
|
|
|
|
|
+- **组件调用规范**: 在组件中应使用`clientManager.get().api.$method`而非直接使用导出的客户端实例,保持架构一致性
|
|
|
|
|
+
|
|
|
|
|
+### API调用结构
|
|
|
|
|
+- **Hono风格**: 生成的客户端使用Hono风格的方法调用(`index.$get`、`index.$post`、`:id.$put`、`:id.$delete`等)
|
|
|
|
|
+- **嵌套路径**: 支持`$path()`方法访问嵌套API端点(如`client.$path('api/areas').$get()`)
|
|
|
|
|
+- **参数传递**: 使用`param`对象传递路径参数,`json`对象传递请求体,`query`对象传递查询参数
|
|
|
|
|
+
|
|
|
|
|
+### 跨UI包集成支持
|
|
|
|
|
+- **统一模拟**: 为简化测试复杂度,特别是跨UI包集成测试场景,测试时应统一模拟`@d8d/shared-ui-components/utils/hc`中的`rpcClient`函数
|
|
|
|
|
+- **跨包优势**: 统一模拟点支持多个UI包组件的API模拟,无需分别模拟各个客户端管理器
|
|
|
|
|
+- **测试规范**: 详细的API模拟策略见[测试策略文档](./testing-strategy.md#api模拟规范)
|
|
|
|
|
+
|
|
|
|
|
+### 架构一致性要求
|
|
|
|
|
+- **统一入口**: 所有API调用必须通过客户端管理器获取实例
|
|
|
|
|
+- **错误处理**: 客户端应提供统一的错误处理机制
|
|
|
|
|
+- **配置管理**: 支持不同环境的API基础URL配置
|
|
|
|
|
+- **生命周期**: 提供`reset()`方法用于测试或重新初始化
|