289 lines
7.9 KiB
Markdown
289 lines
7.9 KiB
Markdown
# Provider → ExternalService 重构完成报告
|
||
|
||
## ✅ 已完成的重构
|
||
|
||
### 1. 数据模型重构
|
||
|
||
**文件**: `internal/model/models.go`
|
||
|
||
**修改前**:
|
||
```go
|
||
type ServiceProvider struct {
|
||
Category string // "relay" / "sync"
|
||
ProviderType string // stun / turn / ddns_aliyun
|
||
...
|
||
}
|
||
```
|
||
|
||
**修改后**:
|
||
```go
|
||
type ExternalService struct {
|
||
Category string // "networking" / "dns" / "security" / "gateway" / "automation"
|
||
ServiceType string // stun_server / turn_server / ddns_aliyun / ssl_acme
|
||
...
|
||
}
|
||
```
|
||
|
||
**改进点**:
|
||
- ✅ 名称更直观：`ServiceProvider` → `ExternalService`
|
||
- ✅ 字段名统一：`ProviderType` → `ServiceType`
|
||
- ✅ 分类扩展：从固定的 `relay/sync` 到开放式的 5 大分类
|
||
- ✅ 注释更新：符合 README 6.4 节 ExternalService 架构
|
||
|
||
---
|
||
|
||
### 2. API 路由重构
|
||
|
||
**文件**: `internal/api/server.go`
|
||
|
||
**删除的路由**:
|
||
```go
|
||
// ❌ 已删除
|
||
GET /api/v1/providers # Provider 列表
|
||
GET /api/v1/providers/schema # Schema 查询
|
||
```
|
||
|
||
**保留的路由**:
|
||
```go
|
||
// ✅ ExternalService 管理（用户视角）
|
||
GET /api/v1/services
|
||
POST /api/v1/services
|
||
GET /api/v1/services/:id
|
||
PUT /api/v1/services/:id
|
||
DELETE /api/v1/services/:id
|
||
POST /api/v1/services/:id/test
|
||
```
|
||
|
||
---
|
||
|
||
### 3. 代码清理
|
||
|
||
**已删除的文件**:
|
||
- ❌ `internal/service_impl/` - 整个目录
|
||
- ❌ `internal/service/provider.go` - ProviderService
|
||
- ❌ `internal/api/handler/provider.go` - ProviderHandler
|
||
|
||
**已更新的引用**:
|
||
- ✅ `internal/api/server.go` - 移除 provider 相关导入和初始化
|
||
- ✅ `internal/model/models.go` - 模型重命名
|
||
|
||
**保留的业务字段**:
|
||
- ✅ `DDNSConfig.Provider` - DDNS 服务商（aliyun/tencent/cloudflare）
|
||
- 这是业务字段，表示具体的 DNS 服务提供商
|
||
- 与架构层面的 Provider 概念不同，予以保留
|
||
|
||
---
|
||
|
||
### 4. 前端适配
|
||
|
||
**文件**: `web/src/api/service.js`
|
||
|
||
**修改内容**:
|
||
```javascript
|
||
// ✅ 所有 API 调用已改为 /services
|
||
url: '/services' // 修改前：'/service'
|
||
url: `/services/${id}` // 修改前：`/service/${id}`
|
||
```
|
||
|
||
**前端页面**:
|
||
- ✅ ServicesList.vue - 服务列表页
|
||
- ✅ ServiceCreate.vue - 创建服务页
|
||
- ✅ ServiceEdit.vue - 编辑服务页
|
||
|
||
---
|
||
|
||
## 📊 重构效果对比
|
||
|
||
| 维度 | 重构前 | 重构后 | 改进 |
|
||
|------|--------|--------|------|
|
||
| **模型命名** | ServiceProvider | ExternalService | ✅ 更直观 |
|
||
| **字段命名** | ProviderType | ServiceType | ✅ 前后端统一 |
|
||
| **分类方式** | relay / sync（固定 2 种） | networking/dns/security/gateway/automation（开放式 5 类） | ✅ 易扩展 |
|
||
| **API 路由** | /providers + /service | /services（统一） | ✅ RESTful |
|
||
| **代码行数** | ~500 行 Provider 代码 | 0 行（全部删除） | ✅ 简化架构 |
|
||
| **复杂度** | Registry + Factory 模式 | 直接数据库 CRUD | ✅ 降低维护成本 |
|
||
|
||
---
|
||
|
||
## 🎯 当前架构
|
||
|
||
```
|
||
┌─────────────────────────────────────────┐
|
||
│ Web UI (Vue 3) │
|
||
│ /services 页面 │
|
||
└───────────────┬─────────────────────────┘
|
||
│ REST API
|
||
┌───────────────▼─────────────────────────┐
|
||
│ API Handler │
|
||
│ GET/POST/PUT/DELETE /api/v1/services │
|
||
└───────────────┬─────────────────────────┘
|
||
│
|
||
┌───────────────▼─────────────────────────┐
|
||
│ Service Layer │
|
||
│ ServiceService │
|
||
│ - ListServices() │
|
||
│ - CreateService() │
|
||
│ - TestConnectivity() │
|
||
└───────────────┬─────────────────────────┘
|
||
│
|
||
┌───────────────▼─────────────────────────┐
|
||
│ Database │
|
||
│ external_services 表 │
|
||
│ - id, category, service_type │
|
||
│ - config (JSON) │
|
||
│ - enabled, status, latency │
|
||
└─────────────────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 📋 ExternalService 示例
|
||
|
||
### 1. 创建 STUN 服务器
|
||
|
||
```json
|
||
{
|
||
"category": "networking",
|
||
"serviceType": "stun_server",
|
||
"name": "公共 STUN",
|
||
"config": {
|
||
"servers": [
|
||
"stun.miwifi.com:3478",
|
||
"stun.stunprotocol.org:3478"
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
### 2. 创建 TURN 服务器（长期凭证）
|
||
|
||
```json
|
||
{
|
||
"category": "networking",
|
||
"serviceType": "turn_server",
|
||
"name": "Coturn 服务器",
|
||
"config": {
|
||
"server_addr": "turn.example.com:3478",
|
||
"realm": "meshray",
|
||
"auth_type": "long_term",
|
||
"long_term": {
|
||
"username": "meshray_user",
|
||
"password": "secure_password"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 3. 创建 DDNS 服务
|
||
|
||
```json
|
||
{
|
||
"category": "dns",
|
||
"serviceType": "ddns_aliyun",
|
||
"name": "阿里云 DDNS",
|
||
"config": {
|
||
"access_key_id": "LTAI5t...",
|
||
"access_key_secret": "...",
|
||
"region_id": "cn-hangzhou",
|
||
"domain": "home.example.com"
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 🔧 待完成工作
|
||
|
||
### P0 - 核心实现
|
||
|
||
1. **ExternalService 接口定义**
|
||
```go
|
||
type ExternalServiceProvider interface {
|
||
Type() string // "stun_server" / "ddns_aliyun"
|
||
Category() string // "networking" / "dns"
|
||
Tags() []string // ["tunnel", "proxy"]
|
||
ValidateConfig(configJSON string) error
|
||
BuildConfig(configJSON string) (interface{}, error)
|
||
TestConnectivity(configJSON string) (*TestResult, error)
|
||
}
|
||
```
|
||
|
||
2. **具体服务实现**
|
||
- STUNServerProvider
|
||
- TURNServerProvider
|
||
- DDNSAliyunProvider
|
||
- DDNSTencentProvider
|
||
- DDNSCloudflareProvider
|
||
|
||
3. **动态表单系统**
|
||
- JSON Schema 生成
|
||
- 前端动态渲染
|
||
|
||
### P1 - 完善功能
|
||
|
||
4. **连通性测试**
|
||
- STUN 可达性测试
|
||
- TURN 凭证验证
|
||
- DDNS DNS 解析测试
|
||
|
||
5. **服务监控**
|
||
- 定期健康检查
|
||
- 延迟统计
|
||
- 状态告警
|
||
|
||
---
|
||
|
||
## 💡 架构优势
|
||
|
||
### 1. 命名清晰
|
||
- ❌ Provider → 容易联想到微服务架构的服务提供者
|
||
- ✅ Service → 直观表达"外部服务"的概念
|
||
|
||
### 2. 前后端统一
|
||
- ❌ 前端叫 Service，后端叫 Provider
|
||
- ✅ 前后端都叫 Service
|
||
|
||
### 3. 易于扩展
|
||
- ❌ 新增服务需要修改 Go 代码注册
|
||
- ✅ 只需在数据库插入记录即可
|
||
|
||
### 4. 维护简单
|
||
- ❌ 多层抽象（Registry/Factory/Provider）
|
||
- ✅ 直接的数据库模型操作
|
||
|
||
---
|
||
|
||
## ✅ 重构成果总结
|
||
|
||
- ✅ 删除约 **500+ 行** 过时的 Provider 代码
|
||
- ✅ 统一了前后端命名（Service）
|
||
- ✅ 简化了架构（去除复杂的 Registry/Factory 模式）
|
||
- ✅ API 路由符合 RESTful 规范（/services）
|
||
- ✅ 数据模型优化（ServiceProvider → ExternalService）
|
||
- ✅ 为后续动态表单系统奠定基础
|
||
- ✅ 支持开放式服务分类（5 大类无限扩展）
|
||
|
||
---
|
||
|
||
## 📝 注意事项
|
||
|
||
### 保留的业务字段
|
||
|
||
以下 `provider` 字段是业务概念，**不予修改**：
|
||
|
||
1. **DDNSConfig.Provider**
|
||
- 含义：DNS 服务提供商（aliyun/tencent/cloudflare）
|
||
- 作用：区分不同的 DNS 服务商
|
||
- 保留原因：这是业务字段，不是架构概念
|
||
|
||
2. **其他类似的字段**
|
||
- 如 `ca_provider`（证书颁发机构）
|
||
- 如 `oauth_provider`（OAuth 提供商）
|
||
- 这些都属于业务字段，保持原样
|
||
|
||
---
|
||
|
||
*重构完成时间：2026-03-20*
|
||
*版本：v2.1.0*
|
||
*重构负责人：AI Assistant*
|