# 编码标准

## 版本信息
| 版本 | 日期 | 描述 | 作者 |
|------|------|------|------|
| 2.6 | 2025-12-15 | 移除测试策略内容，更新RPC客户端最佳实践，与测试策略文档保持一致 | James |
| 2.5 | 2025-12-12 | 修正测试目录描述，从 `__tests__` 更新为 `tests` | Bob (Scrum Master) |
| 2.4 | 2025-09-20 | 与主架构文档版本一致 | Winston |

## 现有标准合规性
- **代码风格**: TypeScript严格模式，一致的缩进和命名
- **linting规则**: 已配置ESLint，支持TypeScript和React
- **文档风格**: 代码注释良好，架构文档完整
- **测试策略**: 独立文档 `testing-strategy.md` 包含完整的测试规范和API模拟策略

## 架构原则
- **模块化设计**: 基于monorepo的模块化架构，支持按需安装
- **类型安全**: 全面使用TypeScript，确保编译时类型检查
- **依赖注入**: 通过客户端管理器模式实现依赖注入，便于测试和替换
- **关注点分离**: 业务逻辑、数据访问、UI呈现分层清晰
- **可扩展性**: 支持单租户和多租户部署模式

## 关键编码规范
- **命名约定**: 使用camelCase（变量、函数）、PascalCase（类、接口）、kebab-case（文件、目录）
- **代码组织**: 遵循功能分组原则，相关代码放在同一目录
- **错误处理**: 统一使用异常处理，避免静默失败
- **日志记录**: 结构化日志，包含上下文信息和级别
- **配置管理**: 环境变量和配置文件分离，支持不同环境配置
- **安全实践**: 输入验证、输出编码、最小权限原则

## RPC客户端架构最佳实践

### 客户端管理器模式
- **单例模式**: 每个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()`方法用于测试或重新初始化