# 技术规格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示例
```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示例
```sql
-- 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示例
```yaml
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时序图示例
```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）
- 标注关键步骤

## 专题设计

### 示例
```markdown
# 权限设计方案

## 策略
- 使用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是上下文体系的组成部分