chill_notes/AI工程/概念/打样工程.md

打样工程

相关：Harness工程、上下文体系、技术规格DSL

定义

打样工程是提供代码模版和示例，让AI参考生成代码的工程实践。

核心思想：让AI"抄作业"，而不是自由发挥，保证代码风格统一、质量稳定。

核心原则

1. 约定大于配置：通过模版约定代码风格
2. 编排逻辑和原子能力分离：Controller、Service、Repository职责明确
3. 操作者和被操作对象分离：分层清晰

常见工序

1. 简单CRUD（无复用逻辑）

Controller + Command → AppService → Repository → Response对象

示例：

// Controller
@PostMapping("/users")
public Response<UserResponse> createUser(@Valid @RequestBody CreateUserCommand cmd) {
    return Response.success(userAppService.create(cmd));
}

// AppService
public UserResponse create(CreateUserCommand cmd) {
    User user = userRepository.save(User.from(cmd));
    return UserResponse.from(user);
}

// Repository
public User save(User user) {
    userMapper.insert(user);
    return user;
}

2. 复杂CRUD（有复用逻辑）

Controller + Command → AppService → DomainService → Repository → Response对象

示例：

// AppService - 编排逻辑
public UserResponse create(CreateUserCommand cmd) {
    // 1. 校验用户名唯一
    domainService.checkUsernameUnique(cmd.getUsername());
    // 2. 加密密码
    String encryptedPassword = domainService.encryptPassword(cmd.getPassword());
    // 3. 保存用户
    User user = User.from(cmd, encryptedPassword);
    userRepository.save(user);
    // 4. 发送欢迎邮件
    domainService.sendWelcomeEmail(user);
    return UserResponse.from(user);
}

// DomainService - 原子能力
public void checkUsernameUnique(String username) {
    if (userRepository.existsByUsername(username)) {
        throw new BusinessException("用户名已存在");
    }
}

3. 复杂查询

Controller + Query对象 → AppService → QueryPO（或复用PO）→ Response对象

示例：

// Controller
@GetMapping("/users")
public Response<Page<UserResponse>> listUsers(@Valid UserQuery query) {
    return Response.success(userAppService.list(query));
}

// AppService
public Page<UserResponse> list(UserQuery query) {
    Page<UserPO> page = userRepository.findByQuery(query);
    return page.map(UserResponse::from);
}

// Repository
public Page<UserPO> findByQuery(UserQuery query) {
    // 构建查询条件
    // 执行分页查询
    // 返回分页结果
}

三层架构

Controller层

• 职责：接收请求、参数校验、调用Service
• 输入：Command/Query对象
• 输出：Response对象
• 不包含业务逻辑

Service层

• AppService：应用服务，编排逻辑
• DomainService：领域服务，复杂业务逻辑
• 职责：编排业务逻辑、调用DomainService/Repository

Repository层

• 职责：数据持久化
• 输入：实体对象
• 输出：实体对象或PO

参考代码

• DDD微服务示例：https://github.com/domain-driven-design/ddd-microservices

为什么需要打样工程

• AI生成代码质量不稳定：需要模版约束
• 不同AI工具风格不同：需要统一风格
• AI不知道最佳实践：需要沉淀最佳实践

优势

1. 提高代码质量：基于模版生成，质量有保障
2. 统一代码风格：所有代码遵循相同的风格
3. 减少Review成本：代码符合规范，Review更快
4. 知识沉淀：最佳实践沉淀在模版中

挑战

• 初始成本：需要建立打样工程
• 维护成本：需要持续维护模版
• 灵活性：模版可能限制创新

最佳实践

1. 建立打样工程：提供标准的代码模版
2. 分层清晰：Controller、Service、Repository职责明确
3. 工序标准化：简单CRUD、复杂CRUD、复杂查询各有标准
4. AI参考打样：让AI根据打样工程生成代码

相关概念

• Harness工程：打样工程是Harness的组成部分
• 上下文体系：打样工程是上下文体系的组成部分
• 技术规格DSL：打样工程使用技术规格DSL