221 lines
5.5 KiB
Markdown
Executable File
221 lines
5.5 KiB
Markdown
Executable File
# 技术规格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是上下文体系的组成部分
|