如何设计一套 Java 项目的 Skill 体系

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

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

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

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

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

真正的威力在于：

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

这就像：

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

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

二、什么是 Skill 体系？

定义

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

它不是简单的 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）

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

示例：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;
}

2️⃣ 数据层 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);
}

3️⃣ 业务层 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;
}
}

4️⃣ 控制层 Skill（Controller Layer）

职责： 生成 API 接口代码

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

5️⃣ 通用能力 Skill（Common Layer）

职责： 提供横向通用能力

6️⃣ 测试层 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.yaml

skill: 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：忽略测试

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

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

十五、收益评估

量化指标

质量提升

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

成本降低

假设一个团队 10 人，每人每天节省 2 小时

每月节省：10 人 × 2 小时 × 22 天 = 440 小时
每年节省：440 × 12 = 5280 小时

按年薪 30 万计算（时薪约 150 元）：
每年节省成本：5280 × 150 = 79.2 万元

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

传统开发模式

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

Skill 体系模式

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

本质变化

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

十七、下一步行动

立即可以做的

1 个月内完成

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