Java 项目 Skill 体系架构设计与实战
Java 项目中 Skill 体系的架构设计,涵盖分层模型(基础层、数据层、业务层等)、设计原则(单一职责、可组合性等)、核心模块定义、组合模式(链式、并行等)以及配置管理、版本控制和质量保障机制。通过实战案例展示 CRUD 功能编排,并提供实施路线图与收益评估,旨在帮助团队从手工开发转向积木式组装,提升效率与代码质量。

Java 项目中 Skill 体系的架构设计,涵盖分层模型(基础层、数据层、业务层等)、设计原则(单一职责、可组合性等)、核心模块定义、组合模式(链式、并行等)以及配置管理、版本控制和质量保障机制。通过实战案例展示 CRUD 功能编排,并提供实施路线图与收益评估,旨在帮助团队从手工开发转向积木式组装,提升效率与代码质量。

关键词:Skill 体系 | 架构设计 | 模块化 | 可组合 | 工程化思维
前面两篇文章,我们分别讲了:
但如果只是零散的 Skill,那还只是"工具集"。
真正的威力在于:
把多个 Skill 组织成体系,形成协同作战的能力矩阵
这就像:
从"点"到"面",从"工具"到"系统",这才是质的飞跃。
Skill 体系 = 多个相互协作的 Skill + 统一的规范 + 清晰的调用关系
它不是简单的 Skill 堆砌,而是:
把 Skill 体系想象成乐高积木:
单个 Skill = 一块积木
Skill 体系 = 积木系统(有标准接口,可以任意组合)
按照 Java 项目的分层架构来设计 Skill 体系。
┌─────────────────────────────────────┐
│ 前端交互层 Skill │
│ (API 文档、接口测试) │
└─────────────────────────────────────┘
↓
┌─────────────────────────────────────┐
│ Controller 层 Skill │
│ (接口定义、参数校验、返回封装) │
└─────────────────────────────────────┘
↓
┌─────────────────────────────────────┐
│ Service 层 Skill │
│ (业务逻辑、事务控制、流程编排) │
└─────────────────────────────────────┘
↓
┌─────────────────────────────────────┐
│ Data 层 Skill │
│ (数据访问、SQL 生成、实体映射) │
└─────────────────────────────────────┘
↓
┌─────────────────────────────────────┐
│ 基础设施 Skill │
│ (工具类、配置类、常量定义) │
└─────────────────────────────────────┘
除了纵向分层,还有横向的通用能力 Skill:
├── DTO 转换 Skill(对象映射)
├── 异常处理 Skill(统一异常)
├── 日志记录 Skill(日志模板)
├── 参数校验 Skill(校验规则)
├── 分页查询 Skill(分页逻辑)
└── 单元测试 Skill(测试模板)
每个 Skill 只做一件事,做好一件事。
❌ 反例:
BadSkill: 生成整个用户管理模块
(包含 Controller、Service、Mapper、DTO、VO...)
这太大了,一个 skill 只负责一件事
✅ 正例:
ControllerSkill: 只生成 Controller 方法
ServiceSkill: 只生成 Service 方法
MapperSkill: 只生成 Mapper 接口
...
Skill 之间可以自由组合,完成复杂任务。
Controller Skill + Service Skill + Mapper Skill = 完整的 CRUD 功能
所有 Skill 遵循统一的输入输出规范。
# 标准输入格式
skill: SkillName
version: 1.0.0
params:
param1: value1
param2: value2
# 标准输出格式
result:
code: 成功的代码
files:
- 需要创建的文件
tips: 使用提示
Skill 支持团队规范定制。
# 团队规范配置
team_standards:
code_style: alibaba # 代码风格
naming_convention: camelCase # 命名规范
return_type: Result<T> # 返回类型
log_framework: slf4j # 日志框架
doc_tool: swagger # 文档工具
Skill 升级时,保持向后兼容,不破坏已有调用。
V1.0 → V1.1 → V2.0
↓ ↓ ↓
兼容 兼容 (主版本可破坏)
职责: 提供最基础的代码生成能力
| 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 名称 | 功能描述 | 依赖 |
|---|---|---|
| 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 名称 | 功能描述 | 依赖 |
|---|---|---|
| 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;
}
}
职责: 生成 API 接口代码
| Skill 名称 | 功能描述 | 依赖 |
|---|---|---|
| ControllerMethodSkill | 生成单个接口方法 | ServiceSkill |
| RestControllerSkill | 生成完整 Controller | ServiceSkill |
| RequestMappingSkill | 生成路由映射 | - |
| ValidationSkill | 添加参数校验 | - |
(参考前一篇文章的详细内容)
职责: 提供横向通用能力
| Skill 名称 | 功能描述 | 适用场景 |
|---|---|---|
| BeanCopySkill | 对象拷贝代码 | DTO/VO/Entity 转换 |
| ExceptionHandlerSkill | 异常处理器 | 统一异常处理 |
| ValidatorSkill | 自定义校验器 | 复杂校验规则 |
| PageSkill | 分页查询模板 | 列表查询 |
| BatchOperationSkill | 批量操作模板 | 批量增删改 |
职责: 自动生成测试代码
| Skill 名称 | 功能描述 |
|---|---|
| UnitTestSkill | 生成单元测试 |
| MockSkill | 生成 Mock 对象 |
| IntegrationTestSkill | 生成集成测试 |
| TestDataSkill | 生成测试数据 |
一个 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
多个 Skill 同时执行,互不依赖。
┌─→ DTO Skill ─┬─→ VO Skill
Entity ─┼
└─→ Query Skill
一个 Skill 内部调用其他 Skill。
ComplexFeatureSkill {
调用 ControllerSkill
调用 ServiceSkill
调用 MapperSkill
调用 TestSkill
}
根据条件选择性调用 Skill。
if (需要缓存) {
调用 CacheSkill
}
if (需要分页) {
调用 PageSkill
}
为"商品管理"模块自动生成完整的 CRUD 功能。
# ===== 第一阶段:基础设施 =====
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-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
遵循语义化版本(Semantic Versioning):
主版本号。次版本号。修订号
例如:2.1.3
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 都需要有测试用例。
# 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"
生成的代码需要通过质量检查。
quality_check:
- checkstyle: true # 代码风格检查
- pmd: true # 代码质量检查
- spotbugs: true # Bug 检查
- compile: true # 编译检查
- unit_test: true # 单元测试覆盖率
每个 Skill 必须有完整文档。
# Skill 文档模板
## 基本信息
- 名称:XXXSkill
- 版本:1.0.0
- 作者:XXX
- 更新日期:2024-01-15
## 功能描述
简要描述 Skill 的功能和用途
## 输入参数
详细说明所有输入参数
## 输出结果
详细说明输出内容
## 使用示例
提供完整的使用示例
## 注意事项
列出使用时需要注意的问题
## 依赖关系
列出依赖的其他 Skill
## 更新日志
记录版本更新历史
Skill 体系应该支持插件式扩展。
核心框架(Skill Engine)
↓
加载器(Skill Loader)
↓
Skill 仓库(Skill Repository)
↓
├── 官方 Skill
├── 团队 Skill
└── 个人 Skill
开发者可以创建自定义 Skill。
# my-custom-skill.yamlskill: MyCustomSkill
extends: BaseSkill # 继承基础 Skill
version: 1.0.0
# 自定义逻辑
custom_logic:
template: |
// 自定义代码模板
@Service
public class ${className} {
// ...
}
目标: 实现核心 Skill,验证可行性
时间:2-4 周
交付物:
✓ EntitySkill
✓ MapperSkill
✓ ServiceSkill
✓ ControllerSkill
✓ 基础配置文件
目标: 完善 Skill 体系,建立规范
时间:4-6 周
交付物:
✓ 完整的分层 Skill
✓ Skill 组合模式
✓ 统一配置管理
✓ 版本控制机制
✓ 质量保障体系
目标: 实现全流程自动化
时间:4-8 周
交付物:
✓ Skill 编排引擎
✓ 可视化配置界面
✓ 批量生成能力
✓ CI/CD 集成
目标: 引入 AI 能力,智能推荐
时间:持续迭代
交付物:
✓ 智能 Skill 推荐
✓ 自动化测试生成
✓ 代码优化建议
✓ 性能分析
skill-repository/
├── README.md
├── skills/
│ ├── foundation/
│ │ ├── EntitySkill/
│ │ │ ├── skill.yaml
│ │ │ ├── template.ftl
│ │ │ └── README.md
│ │ └── DTOSkill/
│ ├── data/
│ ├── service/
│ ├── controller/
│ └── common/
├── examples/
├── docs/
└── tests/
# 发布 Skill 到团队仓库
skill_publish:
name: ServiceImplSkill
version: 2.0.0
category: service
tags: [SpringBoot, MyBatisPlus, Transaction]
author: zhangsan
review: required # 需要审核
visibility: team # 团队可见
不要一开始就设计复杂的体系,从简单开始。
建议: 先实现 3-5 个核心 Skill,验证价值后再扩展。
不同 Skill 的输入输出格式不一致。
建议: 制定统一的接口规范,严格执行。
Skill 没有文档,别人无法使用。
建议: 文档和代码同步更新,不写文档不上线。
把团队特定的规范硬编码在 Skill 中。
建议: 使用配置文件,支持定制化。
生成的代码没有经过充分测试。
建议: 建立自动化测试机制,保证代码质量。
| 指标 | 传统方式 | 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 → 配置参数 → 生成代码 → 组装 → 上线
(核心是"组装",不是"手写")
人力密集型开发 --> 能力复用型开发 每次从零开始 --> 站在巨人肩膀上

微信公众号「极客日志」,在微信中扫描左侧二维码关注。展示文案:极客日志 zeeklog
查找任何按下的键的javascript键代码、代码、位置和修饰符。 在线工具,Keycode 信息在线工具,online
JavaScript 字符串转义/反转义;Java 风格 \uXXXX(Native2Ascii)编码与解码。 在线工具,Escape 与 Native 编解码在线工具,online
使用 Prettier 在浏览器内格式化 JavaScript 或 HTML 片段。 在线工具,JavaScript / HTML 格式化在线工具,online
Terser 压缩、变量名混淆,或 javascript-obfuscator 高强度混淆(体积会增大)。 在线工具,JavaScript 压缩与混淆在线工具,online
生成新的随机RSA私钥和公钥pem证书。 在线工具,RSA密钥对生成器在线工具,online
基于 Mermaid.js 实时预览流程图、时序图等图表,支持源码编辑与即时渲染。 在线工具,Mermaid 预览与可视化编辑在线工具,online