216 lines
7.0 KiB
Markdown
216 lines
7.0 KiB
Markdown
# 概要设计文档：微服务配置管理中心 (Registry)
|
||
|
||
## 1. 系统架构
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
A[浏览器 Browser] --> B[Express Web Server]
|
||
B --> C[路由层 Router]
|
||
C --> D[项目模块 Project Service]
|
||
C --> E[配置模块 Config Service]
|
||
D --> F[JSON 持久化层 Persistence]
|
||
E --> F
|
||
F --> G[(JSON 文件存储)]
|
||
```
|
||
|
||
## 2. 技术选型
|
||
|
||
| 层级 | 技术 | 说明 |
|
||
|------|------|------|
|
||
| 后端框架 | Express 4.x | 轻量级 HTTP 服务 |
|
||
| 前端 | 原生 HTML/CSS/JS | 无框架依赖，降低复杂度 |
|
||
| 持久化 | JSON 文件 | 当前实现，简单可靠 |
|
||
| 模板引擎 | EJS | 服务端渲染基础页面 |
|
||
| 图标 | 内联 SVG | 不依赖第三方图标库 |
|
||
|
||
## 3. 数据模型
|
||
|
||
### 3.1 项目 (Project)
|
||
|
||
```json
|
||
{
|
||
"id": "proj-001",
|
||
"name": "用户服务",
|
||
"description": "用户微服务配置",
|
||
"enableIdc": true,
|
||
"enableEnvironment": true,
|
||
"enableGroup": true,
|
||
"idcMapping": "path",
|
||
"environmentMapping": "path",
|
||
"groupMapping": "label",
|
||
"createdAt": "2026-07-15T10:00:00Z",
|
||
"updatedAt": "2026-07-15T10:00:00Z"
|
||
}
|
||
```
|
||
|
||
字段说明：
|
||
- `enableXxx`：维度是否启用，创建后不可修改。
|
||
- `xxxMapping`：维度映射方式，`path` 表示作为配置存储路径前缀，`label` 表示仅作筛选标签、不进入路径。创建后可通过映射配置接口调整。
|
||
|
||
### 3.2 配置项 (ConfigItem)
|
||
|
||
```json
|
||
{
|
||
"id": "cfg-001",
|
||
"projectId": "proj-001",
|
||
"path": "华北/dev/用户模块/db.host",
|
||
"key": "db.host",
|
||
"value": "192.168.1.100",
|
||
"type": "string",
|
||
"description": "数据库主机地址",
|
||
"purpose": "指定 MySQL 数据库连接地址",
|
||
"valueRange": "合法 IPv4 地址",
|
||
"createdAt": "2026-07-15T10:00:00Z",
|
||
"updatedAt": "2026-07-15T10:00:00Z"
|
||
}
|
||
```
|
||
|
||
### 3.3 配置路径构建规则
|
||
|
||
配置路径由“维度映射方式”与“嵌套键”共同决定：
|
||
|
||
```
|
||
路径模板 = [映射为 path 的维度前缀...]/嵌套键
|
||
|
||
- 维度启用且映射为 path → 该维度值作为路径前缀
|
||
- 维度启用且映射为 label → 该维度不进入路径，仅作维度栏筛选
|
||
- 维度未启用 → 跳过
|
||
- 配置键 key 自身可用 / 嵌套多级（json 类型在展示时按 . 分割）
|
||
```
|
||
|
||
示例（机房=path、环境=path、分组=label）：
|
||
- 配置键 `db/host`，机房 `华北`，环境 `dev`，分组 `用户模块`
|
||
- 生成路径：`华北/dev/db/host`（分组作为标签筛选，不进入路径）
|
||
|
||
示例（全部映射为 path）：
|
||
- 配置键 `db.host` → 路径 `华北/dev/用户模块/db.host`
|
||
|
||
## 4. API 设计
|
||
|
||
### 4.1 项目接口
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| GET | `/api/projects` | 获取项目列表 |
|
||
| GET | `/api/projects/:id` | 获取项目详情 |
|
||
| POST | `/api/projects` | 创建项目（含维度开关与映射方式） |
|
||
| PUT | `/api/projects/:id/mappings` | 更新维度映射方式（path/label） |
|
||
| DELETE | `/api/projects/:id` | 删除项目 |
|
||
|
||
### 4.2 配置接口
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| GET | `/api/projects/:id/configs` | 获取项目下所有配置 |
|
||
| GET | `/api/projects/:id/configs/:configId` | 获取单个配置详情 |
|
||
| POST | `/api/projects/:id/configs` | 新增配置项 |
|
||
| PUT | `/api/projects/:id/configs/:configId` | 修改配置项 |
|
||
| DELETE | `/api/projects/:id/configs/:configId` | 删除配置项 |
|
||
|
||
### 4.3 模式接口
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| GET | `/api/mode` | 获取当前模式 |
|
||
| PUT | `/api/mode` | 切换模式（plan/edit/readonly） |
|
||
|
||
## 5. 前端界面设计
|
||
|
||
### 5.1 布局结构
|
||
|
||
```
|
||
+--------------------------------------------------+
|
||
| 标题栏：应用名 | 当前项目名 |
|
||
+--------------------------------------------------+
|
||
| 工具栏（分组）：项目 | 模式 | 配置 | 数据 |
|
||
+--------------------------------------------------+
|
||
| 维度栏：机房▼ | 环境▼ | 分组▼ | ⚙映射配置 |
|
||
+------------+-------------------------------------+
|
||
| 树形导航 | 地址栏：📍 路径 [转到][拷贝] |
|
||
| (左侧) | +-------------------------------+ |
|
||
| 📦 项目A | | 键名 | 值 | 类型 | 说明 | |
|
||
| 📁 华北 | |------+----+------+----------| |
|
||
| 📁 dev | | db/host|192.|string|数据库.. | |
|
||
| 📁 db | | db/port|3306|number|数据库.. | |
|
||
| 🔑host| +-------------------------------+ |
|
||
+------------+-------------------------------------+
|
||
| 状态栏 |
|
||
+--------------------------------------------------+
|
||
```
|
||
|
||
界面分区说明：
|
||
- 标题栏：仅展示应用名与当前项目名，与操作区分离。
|
||
- 工具栏：按“项目 / 模式 / 配置 / 数据”分组排列操作按钮。
|
||
- 维度栏：展示已启用维度的筛选下拉与映射方式标记，提供映射配置入口。
|
||
- 地址栏：注册表风格路径框，支持拷贝、粘贴后回车跳转到对应节点。
|
||
- 树形导航：按“path 维度前缀 + 嵌套键”逐级展开，叶子节点（🔑）为真实配置项。
|
||
|
||
### 5.2 三种模式差异化
|
||
|
||
| 功能 | 规划模式 | 编辑模式 | 只读模式 |
|
||
|------|---------|---------|---------|
|
||
| 查看配置 | ✓ | ✓ | ✓ |
|
||
| 新增/删除配置 | ✓ | ✓ | ✗ |
|
||
| 修改值 | ✗ | ✓ | ✗ |
|
||
| 修改类型/说明/用途/范围 | ✓ | ✗ | ✗ |
|
||
| 配置值校验 | 仅格式 | 格式+范围 | 不校验 |
|
||
|
||
## 6. 持久化层设计
|
||
|
||
### 6.1 存储结构
|
||
|
||
```
|
||
data/
|
||
├── projects.json # 项目元数据
|
||
├── configs/
|
||
│ └── {projectId}.json # 每个项目独立配置文件
|
||
└── system.json # 系统级配置（当前模式等）
|
||
```
|
||
|
||
### 6.2 持久化接口（预留扩展）
|
||
|
||
```javascript
|
||
class PersistenceAdapter {
|
||
async loadProjects() {}
|
||
async saveProjects(projects) {}
|
||
async loadConfigs(projectId) {}
|
||
async saveConfigs(projectId, configs) {}
|
||
async loadSystem() {}
|
||
async saveSystem(system) {}
|
||
}
|
||
```
|
||
|
||
当前实现 `JsonFileAdapter`，后续可扩展 `SqliteAdapter`、`NacosAdapter` 等。
|
||
|
||
## 7. 目录结构
|
||
|
||
```
|
||
registry/
|
||
├── docs/
|
||
│ ├── requirements.md # 需求文档
|
||
│ └── design.md # 概要设计文档
|
||
├── data/ # 持久化数据目录
|
||
├── src/
|
||
│ ├── server.js # 服务入口
|
||
│ ├── routes/
|
||
│ │ ├── projects.js # 项目路由
|
||
│ │ └── configs.js # 配置路由
|
||
│ ├── services/
|
||
│ │ ├── projectService.js
|
||
│ │ └── configService.js
|
||
│ ├── persistence/
|
||
│ │ └── jsonAdapter.js # JSON 持久化适配器
|
||
│ └── utils/
|
||
│ └── validator.js # 配置值校验
|
||
├── public/
|
||
│ ├── index.html # 主页面
|
||
│ ├── css/
|
||
│ │ └── style.css # 样式
|
||
│ └── js/
|
||
│ ├── app.js # 主逻辑
|
||
│ ├── tree.js # 树形组件
|
||
│ └── api.js # API 调用封装
|
||
├── package.json
|
||
└── README.md
|
||
```
|