@llryiop/avatar-boot-cli 1.0.0

package/templates/.claude/skills/api-service-module-creator/SKILL.md

@@ -0,0 +1,1114 @@
+---
+name: api-service-module-creator
+description: 在项目中创建标准「API + Service」双模块,用于构建项目目录体系标准
+---
+
+# API + Service 双模块创建技能
+
+## Overview（概述）
+
+本技能用于指导在 Avatar Boot 框架下创建标准的 API + Service 双模块项目结构。这种架构模式将接口定义（API）与实现（Service）分离，使得其他服务可以通过引入 API 模块来调用服务，而无需依赖具体实现。
+
+**重要**：API 模块使用 `avatar-boot-starter-feign` 实现 Feign 客户端，提供开箱即用的 HTTP 客户端功能，包含自动日志记录、TraceId 传播和性能指标监控。详见：[avatar-boot-starter-feign 参考文档](../template/reference/avatar-boot-starter-feign.md)
+
+### 核心特点
+
+**API 模块**：
+- 包含 Feign 客户端接口，使用 `avatar-boot-starter-feign` 实现远程调用
+- 自动集成请求日志、TraceId 传播、性能指标等功能
+- 包含基础 POJO、请求/响应对象、常量定义
+- 依赖最小化，仅包含必要的接口定义
+- 被其他服务引入时，在不配置的情况下能正常启动（使用 `@ConditionalOnProperty` 等条件注解）
+- 模块名是项目名后面加"-api"后缀
+
+**Service 模块（service 模块）**：
+- 实现具体业务功能（Controller、Service、Mapper）
+- 依赖 API 模块
+- 包含完整的业务逻辑和数据访问层
+- 模块名是项目名后面加"-service"后缀
+
+**代码组织原则**：
+- 按功能单元组织代码，而非按技术层次
+- 每个功能单元包含完整的 controller、service、mapper、entity
+- 功能单元之间职责清晰，低耦合
+
+示例目录结构：
+```
+avatar-scaffold-project/
+├── avatar-scaffold-api/                      # API 模块（接口定义）
+│   └── src/main/java/com/iflytek/avatar/
+│       ├── common/                            # 公共模块（跨功能共享）
+│       │   ├── constant/                      # 系统级常量
+│       │   │   └── ApiConstant.java
+│       │   ├── enums/                          # 公共枚举
+│       │   │   └── ResultCodeEnum.java
+│       │   ├── exception/                       # 公共异常
+│       │   │   ├── ScaffoldException.java
+│       │   │   └── ErrorCode.java
+│       │   └── dto/                             # 公共DTO
+│       │       ├── PageRequest.java             # 分页请求基类
+│       │       └── PageResponse.java            # 分页响应基类
+│       │
+│       ├── login/                               # 登录功能模块
+│       │   ├── api/                             # Feign接口定义
+│       │   │   └── LoginFeignClient.java
+│       │   ├── constant/                         # 模块常量
+│       │   │   └── LoginConstant.java
+│       │   ├── enums/                            # 模块枚举
+│       │   │   └── LoginTypeEnum.java
+│       │   ├── exception/                         # 模块异常
+│       │   │   └── LoginException.java
+│       │   └── dto/                               # **DTO目录（统一命名）**
+│       │       ├── request/                       # 请求DTO
+│       │       │   ├── LoginRequest.java
+│       │       │   └── RefreshTokenRequest.java
+│       │       └── response/                      # 响应DTO
+│       │           ├── LoginResponse.java
+│       │           └── TokenInfoResponse.java
+│       │
+│       └── user/                                 # 用户功能模块
+│           ├── api/
+│           │   └── UserFeignClient.java
+│           ├── constant/
+│           │   └── UserConstant.java
+│           ├── enums/
+│           │   └── UserStatusEnum.java
+│           ├── exception/
+│           │   └── UserException.java
+│           └── dto/
+│               ├── request/
+│               │   ├── CreateUserRequest.java
+│               │   ├── UpdateUserRequest.java
+│               │   └── UserQueryRequest.java
+│               └── response/
+│                   ├── UserDetailResponse.java
+│                   └── UserSimpleResponse.java
+│
+└── avatar-scaffold-service/                   # Service 模块（业务实现）
+    └── src/main/java/com/iflytek/avatar/
+        ├── common/                              # 公共实现
+        │   ├── config/                           # 全局配置
+        │   │   ├── MyBatisConfig.java
+        │   │   ├── RedisConfig.java
+        │   │   └── SwaggerConfig.java
+        │   ├── utils/                             # 公共工具类
+        │   │   ├── JwtUtils.java
+        │   │   └── RedisUtils.java
+        │   └── interceptor/                       # 全局拦截器
+        │       └── LoginInterceptor.java
+        │
+        ├── login/                                 # 登录功能实现
+        │   ├── config/                             # 模块配置
+        │   │   └── LoginConfig.java
+        │   ├── controller/                          # REST控制器（实现API）
+        │   │   └── LoginController.java
+        │   ├── service/                             # 业务逻辑层
+        │   │   ├── LoginService.java               # 接口
+        │   │   └── impl/
+        │   │       └── LoginServiceImpl.java       # 实现
+        │   ├── repository/                          # **数据访问层（使用repository）**
+        │   │   ├── mapper/                          # MyBatis Mapper接口
+        │   │   │   └── UserLoginMapper.java
+        │   │   └── entity/                          # **数据库实体（统一用entity）**
+        │   │       ├── UserLoginEntity.java        # 用户登录表实体
+        │   │       └── UserTokenEntity.java        # 用户Token表实体
+        │   ├── converter/                           # **对象转换器（DO <-> DTO）**
+        │   │   └── LoginConverter.java
+        │   └── utils/                               # 模块工具类
+        │       └── LoginUtils.java
+        │
+        └── user/                                    # 用户功能实现
+            ├── controller/
+            │   └── UserController.java
+            ├── service/
+            │   ├── UserService.java
+            │   └── impl/
+            │       └── UserServiceImpl.java
+            ├── repository/
+            │   ├── mapper/
+            │   │   └── UserMapper.java
+            │   └── entity/
+            │       ├── UserEntity.java             # 用户主表实体
+            │       └── UserProfileEntity.java      # 用户档案表实体
+            ├── converter/
+            │   └── UserConverter.java
+            └── validator/                           # **参数校验器**
+                └── UserValidator.java
+```
+
+### 架构规则
+
+1. **功能隔离**：每个业务功能（如 login、user）都有独立的包结构，功能之间完全隔离
+2. **垂直划分**：功能包内包含该功能的所有层次（controller、service、dao、entity），避免水平分层
+3. **API 分离**：API 模块只包含接口定义和数据传输对象（DTO），不包含业务逻辑
+4. **Service 实现**：Service 模块包含具体的业务逻辑实现，实现 API 模块定义的接口
+5. **统一返回格式**：所有 API 接口必须使用 `avatar-boot-core` 包中的 `Result<T>` 类作为返回类型，确保响应格式统一
+
+### 包结构说明
+
+以下说明针对**每个功能模块包**（如 `login/`、`user/`）内的子包。**common/** 为跨功能共享：API 的 common 含 `constant/`、`enums/`、`exception/`、`dto/`（如分页基类）；Service 的 common 含 `config/`、`utils/`、`interceptor/`。详见上文示例目录。
+
+**API 模块包结构**（avatar-scaffold-api，每个功能包下）：
+- `api/` - Feign 客户端接口（如 `LoginFeignClient.java`，基于 `avatar-boot-starter-feign`）
+- `constant/` - 模块常量（如 `LoginConstant.java`）
+- `enums/` - 模块枚举（如 `LoginTypeEnum.java`）
+- `exception/` - 模块异常（如 `LoginException.java`）
+- `dto/` - 数据传输对象（统一命名）
+  - `dto/request/` - 请求 DTO（如 `LoginRequest.java`）
+  - `dto/response/` - 响应 DTO（如 `LoginResponse.java`，被调用方需用 `Result<T>` 包装）
+
+**Service 模块包结构**（avatar-scaffold-service，每个功能包下）：
+- `config/` - 模块配置（如 `LoginConfig.java`）
+- `controller/` - REST 控制器（实现 API 契约，返回 `Result<T>`）
+- `service/` - 业务逻辑层（接口如 `LoginService.java`，实现在 `service/impl/`）
+- `repository/` - 数据访问层（统一使用 repository）
+  - `repository/mapper/` - MyBatis Mapper 接口（如 `UserLoginMapper.java`）
+  - `repository/entity/` - 数据库实体（如 `UserLoginEntity.java`，统一用 entity）
+- `converter/` - 对象转换器（DO/Entity 与 DTO 互转，如 `LoginConverter.java`）
+- `utils/` - 模块工具类（如 `LoginUtils.java`）
+- `validator/` - 参数校验器（可选，如 `UserValidator.java`）
+
+**Result 类使用规范**：
+- 所有 Controller 方法必须返回 `com.iflytek.avatar.boot.entity.response.Result<T>` 类型
+- 成功响应：`Result.success(data)` 或 `Result.success()`
+- 失败响应：`Result.fail(errorCode, errorMessage)` 或 `Result.fail(errorMessage)`
+- Response DTO 作为泛型参数：`Result<UserResponse>`
+- 统一的响应格式确保前后端接口规范一致
+
+## When to Use（使用场景）
+
+### 适用场景
+
+- **创建新的业务模块**：如认证模块、文件服务模块、支付模块等
+- **需要被其他微服务调用**：功能需要通过 Feign 客户端被其他服务调用
+- **需要清晰的接口定义和实现分离**：API 模块作为契约，Service 模块作为实现
+- **多团队协作开发**：API 模块可以先定义好接口，多个团队并行开发
+- **功能模块化管理**：按业务功能组织代码，便于维护和扩展
+
+### 不适用场景
+
+- **简单的单体应用**：如果不需要微服务调用，可以使用单模块结构
+- **纯内部工具类**：不需要对外提供接口的工具类模块
+- **临时测试项目**：快速验证想法的临时项目
+
+## Core Pattern（核心模式）
+
+**关键原则**：
+- 功能内聚：一个功能单元包含该功能的所有代码
+- 职责单一：每个功能单元只负责一个业务领域
+- 低耦合：功能单元之间通过接口交互
+
+## Implementation（实施步骤）
+
+### 步骤 1：创建父模块 POM
+
+创建父模块的 `pom.xml`，定义子模块和公共依赖：
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
+         http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+
+    <parent>
+        <groupId>com.iflytek</groupId>
+        <artifactId>avatar-boot-parent</artifactId>
+        <version>1.0.0-SNAPSHOT</version>
+    </parent>
+
+    <artifactId>user-service</artifactId>
+    <packaging>pom</packaging>
+    <version>1.0.0-SNAPSHOT</version>
+
+    <modules>
+        <module>user-service-api</module>
+        <module>user-service-biz</module>
+    </modules>
+
+    <properties>
+        <java.version>21</java.version>
+        <spring-boot.version>3.5.3</spring-boot.version>
+    </properties>
+</project>
+```
+
+### 步骤 2：创建 API 模块
+
+#### 2.1 创建 API 模块的 pom.xml
+
+**重要**：使用 `avatar-boot-starter-feign` 替代原生 Spring Cloud OpenFeign，获得开箱即用的日志、TraceId 传播和性能监控功能。
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
+         http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+
+    <parent>
+        <groupId>com.iflytek</groupId>
+        <artifactId>user-service</artifactId>
+        <version>1.0.0-SNAPSHOT</version>
+    </parent>
+
+    <artifactId>user-service-api</artifactId>
+
+    <dependencies>
+        <!-- Avatar Boot Starter Feign（推荐使用，包含日志、TraceId、指标等功能） -->
+        <dependency>
+            <groupId>com.iflytek.avatar.boot</groupId>
+            <artifactId>avatar-boot-starter-feign</artifactId>
+        </dependency>
+
+        <!-- Validation API -->
+        <dependency>
+            <groupId>jakarta.validation</groupId>
+            <artifactId>jakarta.validation-api</artifactId>
+        </dependency>
+
+        <!-- Lombok（可选） -->
+        <dependency>
+            <groupId>org.projectlombok</groupId>
+            <artifactId>lombok</artifactId>
+            <optional>true</optional>
+        </dependency>
+    </dependencies>
+</project>
+```
+
+**说明**：
+- `avatar-boot-starter-feign` 已包含 `spring-cloud-starter-openfeign` 依赖
+- 自动提供请求日志记录、TraceId 传播、性能指标监控等功能
+- 详细配置参见：[avatar-boot-starter-feign 参考文档](../template/reference/avatar-boot-starter-feign.md)
+
+#### 2.2 创建 Feign 客户端接口
+
+```java
+package com.iflytek.user.client;
+
+import com.iflytek.user.dto.UserDTO;
+import com.iflytek.user.request.LoginRequest;
+import com.iflytek.user.response.LoginResponse;
+import org.springframework.cloud.openfeign.FeignClient;
+import org.springframework.web.bind.annotation.*;
+
+/**
+ * 用户服务 Feign 客户端
+ *
+ * 注意：使用 @ConditionalOnProperty 确保在未配置时不会启动失败
+ */
+@FeignClient(
+    name = "user-service",
+    path = "/api/user",
+    // 使用条件注解，只有配置了才会启用
+    configuration = UserClientConfiguration.class
+)
+public interface UserClient {
+
+    /**
+     * 用户登录
+     */
+    @PostMapping("/login")
+    LoginResponse login(@RequestBody LoginRequest request);
+
+    /**
+     * 根据 ID 获取用户信息
+     */
+    @GetMapping("/{userId}")
+    UserDTO getUserById(@PathVariable("userId") Long userId);
+
+    /**
+     * 创建用户
+     */
+    @PostMapping
+    UserDTO createUser(@RequestBody UserDTO userDTO);
+}
+```
+
+#### 2.3 创建 Feign 客户端配置类
+
+```java
+package com.iflytek.user.client;
+
+import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
+import org.springframework.context.annotation.Configuration;
+
+/**
+ * Feign 客户端配置
+ *
+ * 只有在配置了 feign.client.user-service.enabled=true 时才会启用
+ */
+@Configuration
+@ConditionalOnProperty(
+    prefix = "feign.client.user-service",
+    name = "enabled",
+    havingValue = "true",
+    matchIfMissing = false  // 默认不启用
+)
+public class UserClientConfiguration {
+    // Feign 客户端的自定义配置
+}
+```
+
+#### 2.4 创建 DTO 和请求/响应对象
+
+```java
+package com.iflytek.user.dto;
+
+import lombok.Data;
+import jakarta.validation.constraints.NotBlank;
+import jakarta.validation.constraints.Email;
+
+/**
+ * 用户数据传输对象
+ */
+@Data
+public class UserDTO {
+
+    private Long id;
+
+    @NotBlank(message = "用户名不能为空")
+    private String username;
+
+    @Email(message = "邮箱格式不正确")
+    private String email;
+
+    private String phone;
+
+    private Integer status;
+}
+```
+
+```java
+package com.iflytek.user.request;
+
+import lombok.Data;
+import jakarta.validation.constraints.NotBlank;
+
+/**
+ * 登录请求
+ */
+@Data
+public class LoginRequest {
+
+    @NotBlank(message = "用户名不能为空")
+    private String username;
+
+    @NotBlank(message = "密码不能为空")
+    private String password;
+}
+```
+
+```java
+package com.iflytek.user.response;
+
+import lombok.Data;
+
+/**
+ * 登录响应
+ */
+@Data
+public class LoginResponse {
+
+    private String token;
+
+    private Long userId;
+
+    private String username;
+
+    private Long expireTime;
+}
+```
+
+### 步骤 3：创建 Service 实现模块（biz 模块）
+
+#### 3.1 创建 biz 模块的 pom.xml
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
+         http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+
+    <parent>
+        <groupId>com.iflytek</groupId>
+        <artifactId>user-service</artifactId>
+        <version>1.0.0-SNAPSHOT</version>
+    </parent>
+
+    <artifactId>user-service-biz</artifactId>
+
+    <dependencies>
+        <!-- 依赖 API 模块 -->
+        <dependency>
+            <groupId>com.iflytek</groupId>
+            <artifactId>user-service-api</artifactId>
+            <version>${project.version}</version>
+        </dependency>
+
+        <!-- Spring Boot Web -->
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter-web</artifactId>
+        </dependency>
+
+        <!-- MyBatis Plus -->
+        <dependency>
+            <groupId>com.baomidou</groupId>
+            <artifactId>mybatis-plus-boot-starter</artifactId>
+        </dependency>
+
+        <!-- MySQL Driver -->
+        <dependency>
+            <groupId>com.mysql</groupId>
+            <artifactId>mysql-connector-j</artifactId>
+        </dependency>
+
+        <!-- Redis -->
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter-data-redis</artifactId>
+        </dependency>
+
+        <!-- Lombok -->
+        <dependency>
+            <groupId>org.projectlombok</groupId>
+            <artifactId>lombok</artifactId>
+            <optional>true</optional>
+        </dependency>
+    </dependencies>
+
+    <build>
+        <plugins>
+            <plugin>
+                <groupId>org.springframework.boot</groupId>
+                <artifactId>spring-boot-maven-plugin</artifactId>
+            </plugin>
+        </plugins>
+    </build>
+</project>
+```
+
+### 步骤 4：按功能单元组织代码
+
+#### 4.1 创建 login 功能单元
+
+**LoginController.java**：
+
+```java
+package com.iflytek.user.login.controller;
+
+import com.iflytek.user.client.UserClient;
+import com.iflytek.user.login.service.LoginService;
+import com.iflytek.user.request.LoginRequest;
+import com.iflytek.user.response.LoginResponse;
+import lombok.RequiredArgsConstructor;
+import org.springframework.validation.annotation.Validated;
+import org.springframework.web.bind.annotation.*;
+
+/**
+ * 登录控制器
+ *
+ * 实现 API 模块定义的接口
+ */
+@RestController
+@RequestMapping("/api/user")
+@RequiredArgsConstructor
+public class LoginController implements UserClient {
+
+    private final LoginService loginService;
+
+    @Override
+    @PostMapping("/login")
+    public LoginResponse login(@Validated @RequestBody LoginRequest request) {
+        return loginService.login(request);
+    }
+
+    // 实现 UserClient 的其他方法...
+}
+```
+
+**LoginService.java**：
+
+```java
+package com.iflytek.user.login.service;
+
+import com.iflytek.user.request.LoginRequest;
+import com.iflytek.user.response.LoginResponse;
+
+/**
+ * 登录服务接口
+ */
+public interface LoginService {
+
+    /**
+     * 用户登录
+     */
+    LoginResponse login(LoginRequest request);
+}
+```
+
+**LoginServiceImpl.java**：
+
+```java
+package com.iflytek.user.login.service.impl;
+
+import com.iflytek.user.login.mapper.UserMapper;
+import com.iflytek.user.login.entity.User;
+import com.iflytek.user.login.service.LoginService;
+import com.iflytek.user.request.LoginRequest;
+import com.iflytek.user.response.LoginResponse;
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Transactional;
+
+/**
+ * 登录服务实现
+ */
+@Slf4j
+@Service
+@RequiredArgsConstructor
+public class LoginServiceImpl implements LoginService {
+
+    private final UserMapper userMapper;
+
+    @Override
+    @Transactional(rollbackFor = Exception.class)
+    public LoginResponse login(LoginRequest request) {
+        // 1. 查询用户
+        User user = userMapper.selectByUsername(request.getUsername());
+        if (user == null) {
+            throw new RuntimeException("用户不存在");
+        }
+
+        // 2. 验证密码
+        if (!user.getPassword().equals(request.getPassword())) {
+            throw new RuntimeException("密码错误");
+        }
+
+        // 3. 生成 token
+        String token = generateToken(user);
+
+        // 4. 构建响应
+        LoginResponse response = new LoginResponse();
+        response.setToken(token);
+        response.setUserId(user.getId());
+        response.setUsername(user.getUsername());
+        response.setExpireTime(System.currentTimeMillis() + 7200000); // 2小时
+
+        return response;
+    }
+
+    private String generateToken(User user) {
+        // Token 生成逻辑
+        return "token_" + user.getId() + "_" + System.currentTimeMillis();
+    }
+}
+```
+
+**UserMapper.java**：
+
+```java
+package com.iflytek.user.login.mapper;
+
+import com.baomidou.mybatisplus.core.mapper.BaseMapper;
+import com.iflytek.user.login.entity.User;
+import org.apache.ibatis.annotations.Mapper;
+import org.apache.ibatis.annotations.Param;
+
+/**
+ * 用户 Mapper
+ */
+@Mapper
+public interface UserMapper extends BaseMapper<User> {
+
+    /**
+     * 根据用户名查询用户
+     */
+    User selectByUsername(@Param("username") String username);
+}
+```
+
+**User.java**（实体类）：
+
+```java
+package com.iflytek.user.login.entity;
+
+import com.baomidou.mybatisplus.annotation.TableId;
+import com.baomidou.mybatisplus.annotation.TableName;
+import lombok.Data;
+
+/**
+ * 用户实体
+ */
+@Data
+@TableName("t_user")
+public class User {
+
+    @TableId
+    private Long id;
+
+    private String username;
+
+    private String password;
+
+    private String email;
+
+    private String phone;
+
+    private Integer status;
+}
+```
+
+### 步骤 5：配置自动装配（可选）
+
+如果需要将模块作为 starter 提供给其他项目使用，可以添加自动配置：
+
+**UserServiceAutoConfiguration.java**：
+
+```java
+package com.iflytek.user.config;
+
+import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
+import org.springframework.context.annotation.ComponentScan;
+import org.springframework.context.annotation.Configuration;
+
+/**
+ * 用户服务自动配置
+ */
+@Configuration
+@ConditionalOnProperty(
+    prefix = "user.service",
+    name = "enabled",
+    havingValue = "true",
+    matchIfMissing = true  // 默认启用
+)
+@ComponentScan(basePackages = "com.iflytek.user")
+public class UserServiceAutoConfiguration {
+    // 自动配置逻辑
+}
+```
+
+在 `src/main/resources/META-INF/spring/` 目录下创建 `org.springframework.boot.autoconfigure.AutoConfiguration.imports`：
+
+```
+com.iflytek.user.config.UserServiceAutoConfiguration
+```
+
+#### 5.1 配置 avatar-boot-starter-feign（推荐）
+
+在 Service 模块的 `application.yml` 中配置 Feign 日志和性能监控：
+
+```yaml
+# Feign 客户端配置
+avatar:
+  feign:
+    logging:
+      enabled: true                    # 启用日志拦截器
+      request-enabled: true            # 记录请求参数
+      response-enabled: true           # 记录响应数据
+      slow-request-threshold: 3000     # 慢请求阈值（毫秒）
+      max-body-length: 1000            # 最大请求体长度
+      trace-id-header: X-Trace-Id      # TraceId 请求头名称
+    metrics:
+      enabled: true                    # 启用指标记录
+
+# 针对特定客户端的配置
+feign:
+  client:
+    config:
+      user-service:
+        connectTimeout: 3000
+        readTimeout: 5000
+        loggerLevel: FULL
+```
+
+**说明**：
+- `avatar-boot-starter-feign` 自动提供请求日志、TraceId 传播、性能指标等功能
+- 可以针对特定客户端进行细粒度配置
+- 详细配置参见：[avatar-boot-starter-feign 参考文档](../template/reference/avatar-boot-starter-feign.md)
+
+### 步骤 6：更新父 POM
+
+确保父模块的 `pom.xml` 包含所有子模块：
+
+```xml
+<modules>
+    <module>user-service-api</module>
+    <module>user-service-biz</module>
+</modules>
+```
+
+## Code Review Checklist（代码审查检查点）
+
+### API 模块检查点
+
+- [ ] **使用 avatar-boot-starter-feign**：API 模块使用 `avatar-boot-starter-feign` 而非原生 OpenFeign
+- [ ] **依赖最小化**：API 模块只依赖必要的接口定义库（avatar-boot-starter-feign、Validation）
+- [ ] **无实现逻辑**：API 模块不包含任何业务实现代码
+- [ ] **接口清晰**：Feign 接口定义清晰，方法命名规范
+- [ ] **条件注解**：Feign 客户端使用 `@ConditionalOnProperty`，确保未配置时不启动失败
+- [ ] **DTO 完整**：请求/响应对象包含必要的验证注解
+- [ ] **常量定义**：常量集中定义在 constant 包中
+
+### Service 模块检查点
+
+- [ ] **分层清晰**：Controller → Service → Mapper 分层明确
+- [ ] **实现接口**：Controller 实现 API 模块的 Feign 接口
+- [ ] **异常处理**：统一的异常处理机制
+- [ ] **事务管理**：Service 方法正确使用 `@Transactional`
+- [ ] **日志记录**：关键操作有日志记录
+- [ ] **参数验证**：Controller 使用 `@Validated` 验证参数
+
+### 功能单元检查点
+
+- [ ] **目录结构**：按功能单元组织，每个功能包含 controller、service、mapper、entity
+- [ ] **命名规范**：类名、方法名、变量名符合规范
+- [ ] **职责单一**：每个功能单元只负责一个业务领域
+- [ ] **低耦合**：功能单元之间通过接口交互，避免直接依赖
+- [ ] **代码复用**：公共逻辑抽取到 common 包或工具类
+
+### 配置检查点
+
+- [ ] **Feign 配置**：正确配置 `avatar-boot-starter-feign` 的日志、TraceId、性能监控等功能
+- [ ] **自动配置条件**：使用 `@ConditionalOnProperty` 等条件注解
+- [ ] **配置属性**：配置项有默认值，有清晰的注释
+- [ ] **文档完整**：README 说明模块功能、使用方式、配置项
+- [ ] **参考文档**：引用 [avatar-boot-starter-feign 参考文档](../template/reference/avatar-boot-starter-feign.md)
+
+## Testing Guidelines（测试指南）
+
+### 测试编写时机
+
+#### 单元测试
+**时机**：每完成一个 Service 方法立即编写
+
+```java
+package com.iflytek.user.login.service;
+
+import com.iflytek.user.login.entity.User;
+import com.iflytek.user.login.mapper.UserMapper;
+import com.iflytek.user.login.service.impl.LoginServiceImpl;
+import com.iflytek.user.request.LoginRequest;
+import com.iflytek.user.response.LoginResponse;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.extension.ExtendWith;
+import org.mockito.InjectMocks;
+import org.mockito.Mock;
+import org.mockito.junit.jupiter.MockitoExtension;
+
+import static org.junit.jupiter.api.Assertions.*;
+import static org.mockito.ArgumentMatchers.anyString;
+import static org.mockito.Mockito.when;
+
+/**
+ * 登录服务单元测试
+ */
+@ExtendWith(MockitoExtension.class)
+class LoginServiceTest {
+
+    @Mock
+    private UserMapper userMapper;
+
+    @InjectMocks
+    private LoginServiceImpl loginService;
+
+    @Test
+    void testLogin_Success() {
+        // Given
+        LoginRequest request = new LoginRequest();
+        request.setUsername("testuser");
+        request.setPassword("password123");
+
+        User user = new User();
+        user.setId(1L);
+        user.setUsername("testuser");
+        user.setPassword("password123");
+
+        when(userMapper.selectByUsername(anyString())).thenReturn(user);
+
+        // When
+        LoginResponse response = loginService.login(request);
+
+        // Then
+        assertNotNull(response);
+        assertEquals(1L, response.getUserId());
+        assertEquals("testuser", response.getUsername());
+        assertNotNull(response.getToken());
+    }
+
+    @Test
+    void testLogin_UserNotFound() {
+        // Given
+        LoginRequest request = new LoginRequest();
+        request.setUsername("nonexistent");
+        request.setPassword("password123");
+
+        when(userMapper.selectByUsername(anyString())).thenReturn(null);
+
+        // When & Then
+        assertThrows(RuntimeException.class, () -> loginService.login(request));
+    }
+}
+```
+
+#### 集成测试
+**时机**：完成一个功能单元后编写
+
+```java
+package com.iflytek.user.login.controller;
+
+import com.iflytek.user.request.LoginRequest;
+import com.iflytek.user.response.LoginResponse;
+import org.junit.jupiter.api.Test;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.test.context.SpringBootTest;
+import org.springframework.boot.test.web.client.TestRestTemplate;
+import org.springframework.http.HttpStatus;
+import org.springframework.http.ResponseEntity;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+/**
+ * 登录功能集成测试
+ */
+@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
+class LoginIntegrationTest {
+
+    @Autowired
+    private TestRestTemplate restTemplate;
+
+    @Test
+    void testLoginEndpoint() {
+        // Given
+        LoginRequest request = new LoginRequest();
+        request.setUsername("testuser");
+        request.setPassword("password123");
+
+        // When
+        ResponseEntity<LoginResponse> response = restTemplate.postForEntity(
+            "/api/user/login",
+            request,
+            LoginResponse.class
+        );
+
+        // Then
+        assertEquals(HttpStatus.OK, response.getStatusCode());
+        assertNotNull(response.getBody());
+        assertNotNull(response.getBody().getToken());
+    }
+}
+```
+
+#### 端到端测试
+**时机**：完成整个模块后编写
+
+```java
+package com.iflytek.user;
+
+import com.iflytek.user.client.UserClient;
+import com.iflytek.user.request.LoginRequest;
+import com.iflytek.user.response.LoginResponse;
+import org.junit.jupiter.api.Test;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.test.context.SpringBootTest;
+import org.springframework.cloud.openfeign.EnableFeignClients;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+/**
+ * 用户服务端到端测试
+ */
+@SpringBootTest
+@EnableFeignClients(clients = UserClient.class)
+class UserServiceE2ETest {
+
+    @Autowired
+    private UserClient userClient;
+
+    @Test
+    void testUserLoginFlow() {
+        // Given
+        LoginRequest request = new LoginRequest();
+        request.setUsername("testuser");
+        request.setPassword("password123");
+
+        // When
+        LoginResponse response = userClient.login(request);
+
+        // Then
+        assertNotNull(response);
+        assertNotNull(response.getToken());
+        assertEquals("testuser", response.getUsername());
+    }
+}
+```
+
+### 测试覆盖率要求
+
+- **单元测试**：Service 层覆盖率 ≥ 80%
+- **集成测试**：Controller 层覆盖率 ≥ 70%
+- **端到端测试**：核心业务流程覆盖率 100%
+
+## Common Mistakes（常见错误）
+
+### 错误 1：API 模块依赖过多
+
+**错误示例**：
+```xml
+<!-- API 模块不应该依赖这些 -->
+<dependency>
+    <groupId>org.springframework.boot</groupId>
+    <artifactId>spring-boot-starter-web</artifactId>
+</dependency>
+<dependency>
+    <groupId>com.baomidou</groupId>
+    <artifactId>mybatis-plus-boot-starter</artifactId>
+</dependency>
+```
+
+**正确做法**：
+API 模块只依赖接口定义所需的最小依赖（Feign、Validation）。
+
+### 错误 2：Controller 未实现 API 接口
+
+**错误示例**：
+```java
+@RestController
+@RequestMapping("/api/user")
+public class LoginController {
+    // 没有实现 UserClient 接口
+    @PostMapping("/login")
+    public LoginResponse login(@RequestBody LoginRequest request) {
+        // ...
+    }
+}
+```
+
+**正确做法**：
+```java
+@RestController
+@RequestMapping("/api/user")
+public class LoginController implements UserClient {
+    // 实现 UserClient 接口
+}
+```
+
+### 错误 3：功能代码混杂
+
+**错误示例**：
+```
+controller/
+  ├── LoginController.java
+  ├── UserController.java
+  └── OrderController.java
+service/
+  ├── LoginService.java
+  ├── UserService.java
+  └── OrderService.java
+```
+
+**正确做法**：
+```
+login/
+  ├── controller/
+  ├── service/
+  └── mapper/
+user/
+  ├── controller/
+  ├── service/
+  └── mapper/
+```
+
+### 错误 4：缺少自动配置条件
+
+**错误示例**：
+```java
+@FeignClient(name = "user-service")
+public interface UserClient {
+    // 没有条件注解，引入后必须配置才能启动
+}
+```
+
+**正确做法**：
+```java
+@FeignClient(
+    name = "user-service",
+    configuration = UserClientConfiguration.class
+)
+public interface UserClient {
+    // ...
+}
+
+@Configuration
+@ConditionalOnProperty(
+    prefix = "feign.client.user-service",
+    name = "enabled",
+    havingValue = "true",
+    matchIfMissing = false
+)
+public class UserClientConfiguration {
+    // ...
+}
+```
+
+### 错误 5：Service 方法直接调用绕过 AOP
+
+**错误示例**：
+```java
+@Service
+public class LoginServiceImpl implements LoginService {
+
+    @Transactional
+    public LoginResponse login(LoginRequest request) {
+        // 直接调用内部方法，事务不生效
+        this.validateUser(request);
+        // ...
+    }
+
+    @Transactional
+    private void validateUser(LoginRequest request) {
+        // ...
+    }
+}
+```
+
+**正确做法**：
+```java
+@Service
+public class LoginServiceImpl implements LoginService {
+
+    @Autowired
+    private UserValidator userValidator;  // 注入其他 Bean
+
+    @Transactional
+    public LoginResponse login(LoginRequest request) {
+        // 通过注入的 Bean 调用，AOP 生效
+        userValidator.validate(request);
+        // ...
+    }
+}
+```
+
+## Summary（总结）
+
+本技能提供了在 Avatar Boot 框架下创建标准 API + Service 双模块结构的完整指南。关键要点：
+
+1. **模块分离**：API 模块定义接口，Service 模块实现功能
+2. **使用 avatar-boot-starter-feign**：API 模块使用 `avatar-boot-starter-feign` 获得开箱即用的日志、TraceId 传播和性能监控功能
+3. **功能组织**：按功能单元组织代码，而非技术层次
+4. **条件注解**：确保 API 模块可独立引用
+5. **Code Review**：每完成一个功能进行审查
+6. **测试驱动**：在适当时机编写测试用例
+
+遵循本技能的指导，可以创建结构清晰、易于维护、可扩展的微服务模块。
+
+**相关参考**：
+- [avatar-boot-starter-feign 参考文档](../template/reference/avatar-boot-starter-feign.md) - Feign 客户端配置和使用详解
+