chill_notes/AI工程/概念/技术规格DSL.md

技术规格DSL

相关：规格驱动开发、Harness工程、上下文体系

定义

技术规格DSL（Domain Specific Language）是使用领域特定语言编写技术规格的方法，包括领域模型、数据库、API、时序图等。

核心思想：使用DSL驱动技术规格，保证一致性和可执行性。

5个模块

模块	表达标准	格式	产出内容	约束/规范
领域模型	PlantUML/Smart Domain	.puml	实体、属性、关系	必须表达实体关系；字段需与数据库一致
数据库	SQL DDL/DBML/Flyway	.sql	表结构、索引、约束	必须可执行；包含索引和外键
API	OpenAPI 3.x	.yaml/.json	接口定义、请求/响应	必须定义schema；字段与模型一致
时序图	PlantUML	.puml	调用流程、系统交互	必须反映真实调用链；包含异常分支
专题设计	Markdown	.md	架构策略	只写策略与规则；强调设计决策

领域模型

PlantUML示例

@startuml
entity User {
  * id : Long <<PK>>
  --
  * username : String(50)
  * email : String(100)
  * role_id : Long <<FK>>
}

entity Role {
  * id : Long <<PK>>
  --
  * name : String(20)
}

User }o--|| Role : "拥有"
note right of User : 聚合根
@enduml

约束要求

• 必须表达实体关系（1:1, 1:N, M:N）
• 字段需与数据库一致
• 标注聚合关系

数据库设计

SQL DDL示例

-- Flyway migration: V1__create_users_table.sql
CREATE TABLE users (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    username VARCHAR(50) NOT NULL UNIQUE,
    email VARCHAR(100) NOT NULL UNIQUE,
    password VARCHAR(255) NOT NULL,
    role_id BIGINT NOT NULL,
    status TINYINT(1) DEFAULT 1,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    INDEX idx_username (username),
    INDEX idx_email (email),
    CONSTRAINT fk_user_role FOREIGN KEY (role_id) REFERENCES roles(id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

约束要求

• 必须可执行
• 使用Flyway/Liquibase管理版本
• 包含索引和外键

API设计

OpenAPI 3.x示例

openapi: 3.0.3
info:
  title: User API
  version: 1.0.0
paths:
  /api/v1/users:
    post:
      summary: 创建用户
      tags: [User]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUserRequest'
      responses:
        '201':
          description: 创建成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResponse'
components:
  schemas:
    CreateUserRequest:
      type: object
      required: [username, email, password]
      properties:
        username:
          type: string
          minLength: 3
          maxLength: 50
        email:
          type: string
          format: email
        password:
          type: string
          minLength: 8

约束要求

• 必须定义schema
• 禁止只写接口说明
• 字段与领域模型一致

时序图

PlantUML时序图示例

@startuml
actor User
participant "UserController" as C
participant "UserService" as S
participant "UserRepository" as R
database "MySQL" as DB

User -> C: POST /api/v1/users
C -> C: 参数校验
C -> S: createUser(CreateUserRequest)
S -> S: 业务规则校验
S -> R: save(User)
R -> DB: INSERT INTO users ...
DB --> R: 返回结果
R --> S: 返回 User
S --> C: 返回 UserResponse
C --> User: 201 Created

alt 用户名已存在
  S --> C: throw DuplicateException
  C --> User: 409 Conflict
end
@enduml

约束要求

• 必须反映真实调用链
• 建议包含异常分支（alt）
• 标注关键步骤

专题设计

示例

# 权限设计方案

## 策略
- 使用RBAC（基于角色的访问控制）
- 权限注解：@RequirePermission("user:create")
- 默认拒绝所有未授权的请求

## 规则
1. 管理员角色拥有所有权限
2. 普通用户只能操作自己的数据
3. 敏感操作需要二次确认

## 设计决策
- 选择RBAC而非ABAC：业务场景简单，角色固定
- 权限存储在Redis：减少数据库查询

约束要求

• 只写"策略与规则"
• 不重复API/DDL
• 强调设计决策

为什么用DSL

• 可执行：DDL可以直接运行，OpenAPI可以生成代码
• AI友好：LLM对DSL的理解比自然语言更精确
• 一致性保证：DSL有语法规则，不容易产生歧义

适用场景

• 复杂项目：需要完整的技术规格
• 团队协作：需要统一的技术规范
• AI辅助开发：需要精确的技术规格

优势

• 一致性：领域模型、数据库、API保持一致
• 可执行：部分DSL可以直接执行
• AI友好：AI可以精确理解DSL
• 可维护：DSL可以版本化

挑战

• 学习成本：需要学习多种DSL
• 维护成本：需要保持DSL的一致性
• 工具支持：需要相应的工具支持

最佳实践

1. 使用DSL：统一技术规格的表示方式
2. 保持一致性：领域模型、数据库、API要一致
3. AI辅助生成：让AI根据规格生成代码
4. 版本控制：技术规格纳入Git管理

相关概念

• 规格驱动开发：技术规格DSL是SDD的组成部分
• Harness工程：技术规格DSL是Harness的组成部分
• 上下文体系：技术规格DSL是上下文体系的组成部分