Update from Sync Service
This commit is contained in:
FNS Service
220
AI工程/概念/技术规格DSL.md
Executable file
220
AI工程/概念/技术规格DSL.md
Executable file
@@ -0,0 +1,220 @@
|
||||
# 技术规格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是上下文体系的组成部分
|
||||
Reference in New Issue
Block a user