Java 项目 Skill 体系设计方案与实战

每个 Skill 只做一件事，做好一件事。

❌ 反例：

BadSkill: 生成整个用户管理模块 
(包含 Controller、Service、Mapper、DTO、VO...)
这太大了，一个 skill 只负责一件事

✅ 正例：

ControllerSkill: 只生成 Controller 方法
ServiceSkill: 只生成 Service 方法
MapperSkill: 只生成 Mapper 接口
...

原则 2：可组合性

Skill 之间可以自由组合，完成复杂任务。

Controller Skill + Service Skill + Mapper Skill = 完整的 CRUD 功能

原则 3：标准化接口

所有 Skill 遵循统一的输入输出规范。

# 标准输入格式
skill: SkillName
version: 1.0.0
params:
  param1: value1
  param2: value2

# 标准输出格式
result:
  code: 成功的代码
files:
  - 需要创建的文件
tips: 使用提示

原则 4：可配置性

Skill 支持团队规范定制。

# 团队规范配置
team_standards:
  code_style: alibaba      # 代码风格
  naming_convention: camelCase # 命名规范
  return_type: Result<T>   # 返回类型
  log_framework: slf4j     # 日志框架
  doc_tool: swagger        # 文档工具

原则 5：向后兼容

Skill 升级时，保持向后兼容，不破坏已有调用。

V1.0 → V1.1 → V2.0
↓         ↓         ↓
兼容      兼容      （主版本可破坏）

五、Skill 体系的核心模块设计

1️⃣ 基础层 Skill（Foundation Layer）

职责： 提供最基础的代码生成能力

示例：EntitySkill

skill: EntitySkill
params:
  table_name: user
  fields:
    - name: id
      type: Long
      primary: true
      auto_increment: true
    - name: username
      type: String
      length: 50
      nullable: false
    - name: email
      type: String
      length: 100

输出：

@Data
@TableName("user")
public class User implements Serializable {
    @TableId(value = "id", type = IdType.AUTO)
    private Long id;
    @TableField("username")
    @NotBlank(message = "用户名不能为空")
    @Size(max = 50, message = "用户名长度不能超过 50")
    private String username;
    @TableField("email")
    @Size(max = 100, message = "邮箱长度不能超过 100")
    private String email;
}

六、数据层 Skill（Data Layer）

职责： 自动化数据访问层代码

示例：MapperSkill

skill: MapperSkill
params:
  entity: User
  base_package: com.example.mapper
  extend: BaseMapper # MyBatis-Plus
methods:
  - selectByUsername
  - selectByEmail
  - updateStatusById

输出：

@Mapper
public interface UserMapper extends BaseMapper<User> {
    /**
     * 根据用户名查询
     */
    User selectByUsername(@Param("username") String username);

    /**
     * 根据邮箱查询
     */
    User selectByEmail(@Param("email") String email);

    /**
     * 更新用户状态
     */
    int updateStatusById(@Param("id") Long id, @Param("status") Integer status);
}

七、业务层 Skill（Service Layer）

职责： 生成业务逻辑代码

示例：ServiceImplSkill

skill: ServiceImplSkill
params:
  interface: UserService
  entity: User
  mapper: UserMapper
  methods:
    - name: createUser
      params: [UserCreateDTO]
      return: Long
      transaction: true
    - name: getUserById
      params: [Long id]
      return: UserVO
      cache: true

输出：

@Service
@Slf4j
public class UserServiceImpl implements UserService {
    @Autowired
    private UserMapper userMapper;

    @Override
    @Transactional(rollbackFor = Exception.class)
    public Long createUser(UserCreateDTO dto) {
        log.info("创建用户：{}", dto);
        // 参数校验
        if (userMapper.selectByUsername(dto.getUsername()) != null) {
            throw new BusinessException("用户名已存在");
        }
        // DTO 转 Entity
        User user = new User();
        BeanUtils.copyProperties(dto, user);
        // 保存
        userMapper.insert(user);
        log.info("用户创建成功，userId={}", user.getId());
        return user.getId();
    }

    @Override
    @Cacheable(value = "user", key = "#id")
    public UserVO getUserById(Long id) {
        log.info("查询用户：id={}", id);
        User user = userMapper.selectById(id);
        if (user == null) {
            throw new BusinessException("用户不存在");
        }
        // Entity 转 VO
        UserVO vo = new UserVO();
        BeanUtils.copyProperties(user, vo);
        return vo;
    }
}

八、控制层 Skill（Controller Layer）

职责： 生成 API 接口代码

注：具体实现参考相关技术文档

九、通用能力 Skill（Common Layer）

职责： 提供横向通用能力

十、测试层 Skill（Test Layer）

职责： 自动生成测试代码

十一、Skill 之间的组合模式

模式 1：链式组合（Pipeline）

一个 Skill 的输出作为下一个 Skill 的输入。

EntitySkill → MapperSkill → ServiceSkill → ControllerSkill

示例：完整的用户管理功能

# 步骤 1：生成实体
skill: EntitySkill
params:
  table: user
output: User.java

# 步骤 2：生成 Mapper
skill: MapperSkill
params:
  entity: User
output: UserMapper.java

# 步骤 3：生成 Service
skill: ServiceSkill
params:
  entity: User
  mapper: UserMapper
output: UserService.java, UserServiceImpl.java

# 步骤 4：生成 Controller
skill: ControllerSkill
params:
  service: UserService
output: UserController.java

模式 2：并行组合（Parallel）

多个 Skill 同时执行，互不依赖。

 ┌─→ DTO Skill
Entity ─┼─→ VO Skill
 └─→ Query Skill

模式 3：嵌套组合（Nested）

一个 Skill 内部调用其他 Skill。

ComplexFeatureSkill {
  调用 ControllerSkill
  调用 ServiceSkill
  调用 MapperSkill
  调用 TestSkill
}

模式 4：条件组合（Conditional）

根据条件选择性调用 Skill。

if (需要缓存) {
  调用 CacheSkill
}
if (需要分页) {
  调用 PageSkill
}

十二、实战：设计一个完整的 CRUD Skill 编排

需求

为"商品管理"模块自动生成完整的 CRUD 功能。

Skill 编排方案

# ===== 第一阶段：基础设施 =====
stage1_foundation:
  - skill: EntitySkill
    input:
      table: product
      fields: [id, name, price, stock, status]
    output: Product.java
  - skill: DTOSkill
    input:
      entity: Product
      dto_types: [CreateDTO, UpdateDTO, QueryDTO]
    output:
      - ProductCreateDTO.java
      - ProductUpdateDTO.java
      - ProductQueryDTO.java
  - skill: VOSkill
    input:
      entity: Product
    output: ProductVO.java

# ===== 第二阶段：数据访问层 =====
stage2_data:
  - skill: MapperSkill
    input:
      entity: Product
      methods: [selectByName, selectByStatus, updateStock]
    output: ProductMapper.java
  - skill: MapperXMLSkill
    input:
      mapper: ProductMapper
    output: ProductMapper.xml

# ===== 第三阶段：业务逻辑层 =====
stage3_service:
  - skill: ServiceInterfaceSkill
    input:
      entity: Product
      methods: [create, update, delete, getById, list]
    output: ProductService.java
  - skill: ServiceImplSkill
    input:
      interface: ProductService
      mapper: ProductMapper
      with_transaction: true
      with_cache: true
    output: ProductServiceImpl.java

# ===== 第四阶段：控制层 =====
stage4_controller:
  - skill: RestControllerSkill
    input:
      service: ProductService
      base_path: /api/product
      methods:
        - name: create
          path: /create
          method: POST
        - name: update
          path: /update
          method: PUT
        - name: delete
          path: /delete/{id}
          method: DELETE
        - name: getById
          path: /{id}
          method: GET
        - name: list
          path: /list
          method: GET
          with_page: true
    output: ProductController.java

# ===== 第五阶段：测试代码 =====
stage5_test:
  - skill: UnitTestSkill
    input:
      target: ProductService
    output: ProductServiceTest.java
  - skill: IntegrationTestSkill
    input:
      target: ProductController
    output: ProductControllerTest.java

执行结果

一键生成 12 个文件：

✅ 生成完成！
实体层：
 ✓ Product.java
 ✓ ProductCreateDTO.java
 ✓ ProductUpdateDTO.java
 ✓ ProductQueryDTO.java
 ✓ ProductVO.java
数据层：
 ✓ ProductMapper.java
 ✓ ProductMapper.xml
业务层：
 ✓ ProductService.java
 ✓ ProductServiceImpl.java
控制层：
 ✓ ProductController.java
测试层：
 ✓ ProductServiceTest.java
 ✓ ProductControllerTest.java

十三、Skill 体系的配置管理

统一配置文件

# skill-config.yaml
# 项目基础信息
project:
  name: ecommerce-platform
  base_package: com.example.ecommerce
  author: Your Name

# 代码规范
standards:
  code_style: alibaba
  naming:
    entity_suffix: ""
    dto_suffix: "DTO"
    vo_suffix: "VO"
    service_suffix: "Service"
    controller_suffix: "Controller"

# 技术栈配置
tech_stack:
  framework: SpringBoot
  orm: MyBatisPlus
  validation: JSR303
  doc: Swagger3
  log: slf4j
  cache: Redis

# 通用配置
common:
  result_wrapper: Result<T>
  exception_handler: GlobalExceptionHandler
  id_type: Long
  id_generator: auto_increment

# 数据库配置
database:
  type: MySQL
  charset: utf8mb4
  engine: InnoDB

# Skill 加载路径
skills:
  load_paths:
    - ./skills/foundation
    - ./skills/data
    - ./skills/service
    - ./skills/controller
    - ./skills/common
    - ./skills/test

十四、Skill 体系的版本管理

版本号规范

遵循语义化版本（Semantic Versioning）：

主版本号。次版本号。修订号
例如：2.1.3

• 主版本号：不兼容的 API 修改
• 次版本号：向后兼容的功能新增
• 修订号：向后兼容的问题修正

Skill 版本声明

skill: ServiceImplSkill
version: 2.1.0
compatibility:
  min_version: 2.0.0 # 最低兼容版本
deprecated: false
changelog:
  - version: 2.1.0
    date: 2024-01-15
    changes:
      - 新增缓存支持
      - 优化事务处理
  - version: 2.0.0
    date: 2023-12-01
    changes:
      - 重构代码结构
      - 破坏性变更：修改输入参数格式

十五、Skill 体系的质量保障

1️⃣ Skill 测试

每个 Skill 都需要有测试用例。

# ServiceImplSkill 测试用例
test_cases:
  - name: 基础功能测试
    input:
      entity: User
      methods: [create, update, delete]
    expect:
      files: [UserService.java, UserServiceImpl.java]
      compilable: true
  - name: 事务注解测试
    input:
      entity: Order
      methods: [create]
      with_transaction: true
    expect:
      contains: "@Transactional"

2️⃣ 输出代码检查

生成的代码需要通过质量检查。

quality_check:
  - checkstyle: true # 代码风格检查
  - pmd: true        # 代码质量检查
  - spotbugs: true   # Bug 检查
  - compile: true    # 编译检查
  - unit_test: true  # 单元测试覆盖率

3️⃣ Skill 文档

每个 Skill 必须有完整文档。

# Skill 文档模板
## 基本信息
- 名称：XXXSkill
- 版本：1.0.0
- 作者：XXX
- 更新日期：2024-01-15

## 功能描述
简要描述 Skill 的功能和用途

## 输入参数
详细说明所有输入参数

## 输出结果
详细说明输出内容

## 使用示例
提供完整的使用示例

## 注意事项
列出使用时需要注意的问题

## 依赖关系
列出依赖的其他 Skill

## 更新日志
记录版本更新历史

十六、Skill 体系的扩展性设计

插件化架构

Skill 体系应该支持插件式扩展。

核心框架（Skill Engine）
↓
加载器（Skill Loader）
↓
Skill 仓库（Skill Repository）
↓
├── 官方 Skill
├── 团队 Skill
└── 个人 Skill

自定义 Skill

开发者可以创建自定义 Skill。

# my-custom-skill.yamlskill: MyCustomSkill
extends: BaseSkill # 继承基础 Skill
version: 1.0.0

# 自定义逻辑
custom_logic:
  template: |
    // 自定义代码模板
    @Service
    public class ${className} {
      // ...
    }

十七、实施路线图

阶段 1：MVP（最小可行产品）

目标： 实现核心 Skill，验证可行性

时间：2-4 周
交付物：
 ✓ EntitySkill
 ✓ MapperSkill
 ✓ ServiceSkill
 ✓ ControllerSkill
 ✓ 基础配置文件

阶段 2：体系化

目标： 完善 Skill 体系，建立规范

时间：4-6 周
交付物：
 ✓ 完整的分层 Skill
 ✓ Skill 组合模式
 ✓ 统一配置管理
 ✓ 版本控制机制
 ✓ 质量保障体系

阶段 3：自动化

目标： 实现全流程自动化

时间：4-8 周
交付物：
 ✓ Skill 编排引擎
 ✓ 可视化配置界面
 ✓ 批量生成能力
 ✓ CI/CD 集成

阶段 4：智能化

目标： 引入 AI 能力，智能推荐

时间：持续迭代
交付物：
 ✓ 智能 Skill 推荐
 ✓ 自动化测试生成
 ✓ 代码优化建议
 ✓ 性能分析

十八、团队协作与 Skill 共享

Skill 仓库管理

skill-repository/
├── README.md
├── skills/
│   ├── foundation/
│   │   ├── EntitySkill/
│   │   │   ├── skill.yaml
│   │   │   ├── template.ftl
│   │   │   └── README.md
│   │   └── DTOSkill/
│   ├── data/
│   ├── service/
│   ├── controller/
│   └── common/
├── examples/
├── docs/
└── tests/

Skill 分享机制

# 发布 Skill 到团队仓库
skill_publish:
  name: ServiceImplSkill
  version: 2.0.0
  category: service
  tags: [SpringBoot, MyBatisPlus, Transaction]
  review: required # 需要审核
  visibility: team # 团队可见

十九、避免的常见陷阱

❌ 陷阱 1：过度设计

不要一开始就设计复杂的体系，从简单开始。

建议： 先实现 3-5 个核心 Skill，验证价值后再扩展。

❌ 陷阱 2：规范不统一

不同 Skill 的输入输出格式不一致。

建议： 制定统一的接口规范，严格执行。

❌ 陷阱 3：缺乏文档

Skill 没有文档，别人无法使用。

建议： 文档和代码同步更新，不写文档不上线。

❌ 陷阱 4：硬编码

把团队特定的规范硬编码在 Skill 中。

建议： 使用配置文件，支持定制化。

❌ 陷阱 5：忽略测试

生成的代码没有经过充分测试。

建议： 建立自动化测试机制，保证代码质量。

二十、收益评估

量化指标

质量提升

• ✅ 代码风格统一
• ✅ 命名规范一致
• ✅ 文档自动生成
• ✅ 最佳实践内置
• ✅ 安全规范保证

成本降低

假设一个团队 10 人，每人每天节省 2 小时
每月节省：10 人 × 2 小时 × 22 天 = 440 小时
每年节省：440 × 12 = 5280 小时
按年薪 30 万计算（时薪约 150 元）：
每年节省成本：5280 × 150 = 79.2 万元

二十一、总结：从"写代码"到"搭积木"

传统开发模式

需求 → 设计 → 手写代码 → 调试 → 测试 → 上线
（每个环节都是手工完成）

Skill 体系模式

需求 → 选择 Skill → 配置参数 → 生成代码 → 组装 → 上线
（核心是"组装"，不是"手写"）

本质变化

人力密集型开发 --> 能力复用型开发 每次从零开始 --> 站在巨人肩膀上

二十二、下一步行动

立即可以做的

1. ✅ 梳理项目中的重复劳动
2. ✅ 识别 3-5 个最高频的场景
3. ✅ 设计第一个 Skill
4. ✅ 小范围试点验证
5. ✅ 收集反馈持续优化

1 个月内完成

• ✅ 搭建基础 Skill 框架
• ✅ 实现核心模块