Java 项目 Skill 体系架构设计与实战

关键词：Skill 体系 | 架构设计 | 模块化 | 可组合 | 工程化思维

一、从单个 Skill 到 Skill 体系：质变的开始

前面两篇文章，我们分别讲了：

• Service Skill：自动生成业务层代码
• Controller Skill：自动生成接口层代码

但如果只是零散的 Skill，那还只是"工具集"。

真正的威力在于：

把多个 Skill 组织成体系，形成协同作战的能力矩阵

这就像：

• 单个技能 = 单兵作战
• Skill 体系 = 特种部队

从"点"到"面"，从"工具"到"系统"，这才是质的飞跃。

二、什么是 Skill 体系？

定义

Skill 体系 = 多个相互协作的 Skill + 统一的规范 + 清晰的调用关系

它不是简单的 Skill 堆砌，而是：

1. 有层次结构：分层设计，职责清晰
2. 有协作关系：Skill 之间可以组合调用
3. 有统一规范：输入输出格式一致
4. 有扩展能力：可以持续添加新 Skill

一个类比

把 Skill 体系想象成乐高积木：

单个 Skill = 一块积木
Skill 体系 = 积木系统（有标准接口，可以任意组合）

• 每块积木都有标准接口（统一规范）
• 可以自由组合（可组合性）
• 可以搭建复杂结构（协同作战）

三、Java 项目的 Skill 体系分层设计

核心思想

按照 Java 项目的分层架构来设计 Skill 体系。

┌─────────────────────────────────────┐
│ 前端交互层 Skill                      │
│ (API 文档、接口测试)                   │
└─────────────────────────────────────┘
↓
┌─────────────────────────────────────┐
│ Controller 层 Skill                   │
│ (接口定义、参数校验、返回封装)         │
└─────────────────────────────────────┘
↓
┌─────────────────────────────────────┐
│ Service 层 Skill                      │
│ (业务逻辑、事务控制、流程编排)         │
└─────────────────────────────────────┘
↓
┌─────────────────────────────────────┐
│ Data 层 Skill                         │
│ (数据访问、SQL 生成、实体映射)           │
└─────────────────────────────────────┘
↓
┌─────────────────────────────────────┐
│ 基础设施 Skill                        │
│ (工具类、配置类、常量定义)             │
└─────────────────────────────────────┘

横向扩展

除了纵向分层，还有横向的通用能力 Skill：

├── DTO 转换 Skill（对象映射）
├── 异常处理 Skill（统一异常）
├── 日志记录 Skill（日志模板）
├── 参数校验 Skill（校验规则）
├── 分页查询 Skill（分页逻辑）
└── 单元测试 Skill（测试模板）

四、Skill 体系的设计原则

原则 1：单一职责

每个 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）

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

Skill 名称	功能描述	输入示例	输出示例
EntitySkill	生成实体类	表结构	Entity 类（含注解）
DTOSkill	生成传输对象	字段列表	DTO/VO 类
EnumSkill	生成枚举类	枚举值列表	Enum 类
ConfigSkill	生成配置类	配置项	@Configuration 类
ConstantSkill	生成常量类	常量列表	常量类

示例：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）

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

Skill 名称	功能描述	依赖
MapperSkill	生成 Mapper 接口	EntitySkill
MapperXMLSkill	生成 Mapper XML	MapperSkill
CRUDSkill	生成标准 CRUD	MapperSkill
ComplexQuerySkill	生成复杂查询	MapperSkill

示例：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）

职责： 生成业务逻辑代码

Skill 名称	功能描述	依赖
ServiceInterfaceSkill	生成 Service 接口	-
ServiceImplSkill	生成 Service 实现	MapperSkill
TransactionSkill	添加事务控制	ServiceImplSkill
CacheSkill	添加缓存逻辑	ServiceImplSkill

示例：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 名称	功能描述	依赖
ControllerMethodSkill	生成单个接口方法	ServiceSkill
RestControllerSkill	生成完整 Controller	ServiceSkill
RequestMappingSkill	生成路由映射	-
ValidationSkill	添加参数校验	-

（参考前一篇文章的详细内容）

九、通用能力 Skill（Common Layer）

职责： 提供横向通用能力

Skill 名称	功能描述	适用场景
BeanCopySkill	对象拷贝代码	DTO/VO/Entity 转换
ExceptionHandlerSkill	异常处理器	统一异常处理
ValidatorSkill	自定义校验器	复杂校验规则
PageSkill	分页查询模板	列表查询
BatchOperationSkill	批量操作模板	批量增删改

十、测试层 Skill（Test Layer）

职责： 自动生成测试代码

Skill 名称	功能描述
UnitTestSkill	生成单元测试
MockSkill	生成 Mock 对象
IntegrationTestSkill	生成集成测试
TestDataSkill	生成测试数据

十一、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 ─┬─→ VO Skill
Entity ─┼
 └─→ 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]
  author: zhangsan
  review: required # 需要审核
  visibility: team # 团队可见

十九、避免的常见陷阱

❌ 陷阱 1：过度设计

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

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

❌ 陷阱 2：规范不统一

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

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

❌ 陷阱 3：缺乏文档

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

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

❌ 陷阱 4：硬编码

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

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

❌ 陷阱 5：忽略测试

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

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

二十、收益评估

量化指标

指标	传统方式	Skill 体系	提升
CRUD 开发时间	2-3 小时	5-10 分钟	20 倍
代码一致性	60%	95%	58%
Bug 率	15%	5%	降低 67%
文档完整性	30%	90%	3 倍
新人上手时间	2-3 周	3-5 天	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 框架
• ✅ 实现核心