common-coding

# 编码技能 ## 功能描述 提供代码编写指导能力，帮助开发者遵循编码规范和最佳实践，提高代码质量和可维护性。 ## 何时使用 在以下情况调用此技能： - 需要编写新代码时 - 需要审查代码质量时 - 需要优化现有代码时 - 需要生成代码文档时 ## 核心功能 - **代码生成**：根据需求生成符合规范的代码 - **代码审查**：检查代码是否符合编码规范 - **代码优化**：提供代码优化建议 - **文档生成**：生成代码文档和注释 - **设计模式推荐**：根据场景推荐合适的设计模式 ## 输入参数 | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | language | String | 是 | 目标编程语言（Java/Python/JavaScript等） | | framework | String | 否 | 使用的框架（Spring Boot/React/Vue等） | | requirement | String | 是 | 功能需求描述 | | styleGuide | String | 否 | 编码风格指南名称 | ## 输出格式 ```json { "status": "SUCCESS", "language": "Java", "framework": "Spring Boot", "code": "生成的代码内容", "explanation": "代码解释和说明", "bestPractices": ["最佳实践1", "最佳实践2"], "improvements": [ { "issue": "问题描述", "suggestion": "改进建议", "severity": "高/中/低" } ] } ``` ## 编码流程 ``` 需求分析 → 技术选型 → 代码设计 → 代码实现 → 代码审查 → 优化改进 → 文档生成 ``` ### 详细步骤 1. **需求分析**：理解业务需求，确定实现方案 2. **技术选型**：选择合适的技术栈和框架 3. **代码设计**：设计类结构、方法签名和数据模型 4. **代码实现**：编写符合规范的代码 5. **代码审查**：检查代码质量和规范合规性 6. **优化改进**：根据审查结果进行优化 7. **文档生成**：编写代码注释和文档 ## 编码规范检查清单 | 检查项 | 说明 | 状态 | |--------|------|------| | 命名规范 | 变量、方法、类命名是否符合规范 | ✅/❌ | | 代码格式 | 缩进、空格、换行是否符合规范 | ✅/❌ | | 注释完整 | 是否有必要的注释说明 | ✅/❌ | | 异常处理 | 是否正确处理异常情况 | ✅/❌ | | 代码复用 | 是否避免重复代码 | ✅/❌ | | 性能优化 | 是否考虑性能问题 | ✅/❌ | | 安全性 | 是否存在安全隐患 | ✅/❌ | | 可测试性 | 代码是否易于测试 | ✅/❌ | ## 最佳实践指南 ### Java 编码规范 1. **命名规范**：类名使用 PascalCase，方法和变量使用 camelCase 2. **代码格式**：使用 4 空格缩进，每行不超过 120 字符 3. **注释规范**：使用 Javadoc 格式，方法必须有注释 4. **异常处理**：使用 try-with-resources，避免空 catch 块 5. **设计原则**：遵循 SOLID 原则，单一职责 ### 外部调用规范 #### 目录结构 所有外部调用相关代码必须放在 `infra` 目录下： ``` src/main/java/com/example/ ├── application/ # 应用层（业务逻辑） ├── domain/ # 领域层（业务实体） └── infra/ # 基础设施层（外部调用） ├── client/ # Remote Client 透传层 ├── proxy/ # Remote Proxy 适配层 └── adapter/ # Remote Adapter 转换层 ``` #### Remote Client 模式 **职责**：透传外部接口，不做业务逻辑处理 **命名约定**：`{ServiceName}RemoteClient` **示例**： ```java // infra/client/UserRemoteClient.java @FeignClient(name = "user-service") public interface UserRemoteClient { @GetMapping("/api/users/{id}") ResponseEntity<UserDTO> getUserById(@PathVariable Long id); @PostMapping("/api/users") ResponseEntity<UserDTO> createUser(@RequestBody CreateUserRequest request); } ``` #### Remote Proxy 模式 **职责**：对外部接口进行适配和调用，添加业务无关的通用处理 **命名约定**：`{ServiceName}RemoteProxy` **示例**： ```java // infra/proxy/UserRemoteProxy.java @Component public class UserRemoteProxy { private final UserRemoteClient userRemoteClient; private final RestTemplate restTemplate; public User getUser(Long id) { try { ResponseEntity<UserDTO> response = userRemoteClient.getUserById(id); if (response.getStatusCode().is2xxSuccessful()) { return convertToDomain(response.getBody()); } throw new RemoteServiceException("Failed to get user"); } catch (FeignException e) { log.warn("Remote call failed, fallback to cache"); return getFromCache(id); } } // 通用重试、熔断、降级处理 @Retryable(maxAttempts = 3) public User createUser(UserCreateCommand command) { // ... } } ``` #### Remote Adapter 模式 **职责**：数据转换和协议适配，将外部数据转换为领域模型 **命名约定**：`{ServiceName}RemoteAdapter` **示例**： ```java // infra/adapter/UserRemoteAdapter.java @Component public class UserRemoteAdapter { private final UserRemoteProxy userRemoteProxy; public UserDomain loadUser(Long userId) { User user = userRemoteProxy.getUser(userId); // 转换为领域模型 return UserDomain.builder() .id(user.getId()) .username(user.getUsername()) .email(user.getEmail()) .build(); } public UserDomain createUser(UserCreateDomain domain) { CreateUserRequest request = CreateUserRequest.builder() .username(domain.getUsername()) .email(domain.getEmail()) .build(); User user = userRemoteProxy.createUser(request); return convertToDomain(user); } } ``` #### 使用规范 | 层次 | 职责 | 适用场景 | |------|------|----------| | Remote Client | 透传调用，无业务逻辑 | 简单的 REST/gRPC 调用 | | Remote Proxy | 通用处理（重试、熔断、降级） | 需要容错处理的调用 | | Remote Adapter | 数据转换、协议适配 | 需要领域模型转换 | #### 调用流程 ``` Application Service → Remote Adapter → Remote Proxy → Remote Client → External Service ``` **说明**： 1. **Application Service**：业务层，调用 Adapter 2. **Remote Adapter**：数据转换，调用 Proxy 3. **Remote Proxy**：通用处理（重试、熔断），调用 Client 4. **Remote Client**：透传调用外部服务 ### Python 编码规范 1. **命名规范**：模块和函数使用 snake_case，类使用 PascalCase 2. **代码格式**：使用 4 空格缩进，每行不超过 79 字符 3. **注释规范**：使用 docstring，遵循 Google 风格 4. **类型提示**：使用类型注解提高代码可读性 5. **代码组织**：合理使用模块和包结构 ### JavaScript/TypeScript 编码规范 1. **命名规范**：变量和函数使用 camelCase，类使用 PascalCase 2. **代码格式**：使用 2 空格缩进，每行不超过 120 字符 3. **注释规范**：使用 JSDoc 格式 4. **异步处理**：使用 async/await，避免回调地狱 5. **类型安全**：TypeScript 项目严格启用类型检查 ## 核心组件 | 组件 | 职责 | 描述 | |------|------|------| | CodeGenerator | 代码生成器 | 根据需求生成代码 | | CodeAnalyzer | 代码分析器 | 分析代码质量和规范 | | PatternRecommender | 模式推荐器 | 推荐合适的设计模式 | | DocGenerator | 文档生成器 | 生成代码文档 | ## 配置要求 ### 环境变量 | 变量名 | 说明 | 默认值 | |--------|------|--------| | CODING_STYLE_GUIDE | 默认编码风格指南 | google | ### 配置文件 ```yaml coding: style-guide: google max-line-length: 120 enforce-type-hints: true ``` ## 扩展指南 ### 添加新语言支持 1. 创建对应语言的代码生成器 2. 定义该语言的编码规范规则 3. 添加代码分析和检查逻辑 ### 添加自定义规则 1. 在规则引擎中添加新规则 2. 定义规则的检查逻辑和修复建议 3. 更新编码规范检查清单 ## 触发条件