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

Java 项目 Skill 体系架构设计与实战 | 极客日志

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

# ===== 第一阶段：基础设施 =====
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

✅ 生成完成！
实体层：
 ✓ 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

主版本号。次版本号。修订号
例如：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:
      - 重构代码结构
      - 破坏性变更：修改输入参数格式

# 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 文档模板
## 基本信息
- 名称：XXXSkill
- 版本：1.0.0
- 作者：XXX
- 更新日期：2024-01-15

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

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

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

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

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

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

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

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

# my-custom-skill.yamlskill: MyCustomSkill
extends: BaseSkill # 继承基础 Skill
version: 1.0.0
# 自定义逻辑
custom_logic:
template: |
  // 自定义代码模板
  @Service
  public class ${className} {
    // ...
  }

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

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

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

时间：持续迭代
交付物：
 ✓ 智能 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 # 团队可见

指标	传统方式	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 → 配置参数 → 生成代码 → 组装 → 上线
（核心是"组装"，不是"手写"）

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

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

二、什么是 Skill 体系？

定义

一个类比

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

核心思想

横向扩展

四、Skill 体系的设计原则

原则 1：单一职责

原则 2：可组合性

原则 3：标准化接口

原则 4：可配置性

原则 5：向后兼容

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

1️⃣ 基础层 Skill（Foundation Layer）

六、数据层 Skill（Data Layer）

七、业务层 Skill（Service Layer）

八、控制层 Skill（Controller Layer）

九、通用能力 Skill（Common Layer）

十、测试层 Skill（Test Layer）

十一、Skill 之间的组合模式

模式 1：链式组合（Pipeline）

模式 2：并行组合（Parallel）

模式 3：嵌套组合（Nested）

模式 4：条件组合（Conditional）

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

需求

Skill 编排方案

执行结果

十三、Skill 体系的配置管理

统一配置文件

十四、Skill 体系的版本管理

版本号规范

Skill 版本声明

十五、Skill 体系的质量保障

1️⃣ Skill 测试

2️⃣ 输出代码检查

3️⃣ Skill 文档

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

插件化架构

自定义 Skill

十七、实施路线图

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

阶段 2：体系化

阶段 3：自动化

阶段 4：智能化

十八、团队协作与 Skill 共享

Skill 仓库管理

Skill 分享机制

十九、避免的常见陷阱

❌ 陷阱 1：过度设计

❌ 陷阱 2：规范不统一

❌ 陷阱 3：缺乏文档

❌ 陷阱 4：硬编码

❌ 陷阱 5：忽略测试

二十、收益评估

量化指标

质量提升

成本降低

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

传统开发模式

Skill 体系模式

本质变化

二十二、下一步行动

立即可以做的

1 个月内完成

微信扫一扫，关注极客日志

更多推荐文章

相关免费在线工具