如何设计一套 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）

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

示例：EntitySkill

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

输出：

@Data@TableName("user")publicclassUserimplementsSerializable{@TableId(value ="id", type =IdType.AUTO)privateLong id;@TableField("username")@NotBlank(message ="用户名不能为空")@Size(max =50, message ="用户名长度不能超过50")privateString username;@TableField("email")@Size(max =100, message ="邮箱长度不能超过100")privateString email;}

2️⃣ 数据层 Skill（Data Layer）

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

示例：MapperSkill

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

输出：

@MapperpublicinterfaceUserMapperextendsBaseMapper<User>{/** * 根据用户名查询 */UserselectByUsername(@Param("username")String username);/** * 根据邮箱查询 */UserselectByEmail(@Param("email")String email);/** * 更新用户状态 */intupdateStatusById(@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@Slf4jpublicclassUserServiceImplimplementsUserService{@AutowiredprivateUserMapper userMapper;@Override@Transactional(rollbackFor =Exception.class)publicLongcreateUser(UserCreateDTO dto){ log.info("创建用户: {}", dto);// 参数校验if(userMapper.selectByUsername(dto.getUsername())!=null){thrownewBusinessException("用户名已存在");}// DTO转EntityUser user =newUser();BeanUtils.copyProperties(dto, user);// 保存 userMapper.insert(user); log.info("用户创建成功, userId={}", user.getId());return user.getId();}@Override@Cacheable(value ="user", key ="#id")publicUserVOgetUserById(Long id){ log.info("查询用户: id={}", id);User user = userMapper.selectById(id);if(user ==null){thrownewBusinessException("用户不存在");}// Entity转VOUserVO vo =newUserVO();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：生成Mapperskill: MapperSkill params:entity: User output: UserMapper.java # 步骤3：生成Serviceskill: ServiceSkill params:entity: User mapper: UserMapper output: UserService.java, UserServiceImpl.java # 步骤4：生成Controllerskill: 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:truewith_cache:trueoutput: 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:trueoutput: 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:falsechangelog:-version: 2.1.0 date:2024-01-15changes:- 新增缓存支持 - 优化事务处理 -version: 2.0.0 date:2023-12-01changes:- 重构代码结构 - 破坏性变更：修改输入参数格式 

十、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:trueexpect: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 # 继承基础 Skillversion: 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. ✅ 梳理项目中的重复劳动
2. ✅ 识别 3-5 个最高频的场景
3. ✅ 设计第一个 Skill
4. ✅ 小范围试点验证
5. ✅ 收集反馈持续优化

1 个月内完成

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