@umacloud/knowledge 1.0.1

package/development/00-governance/document-template.md

@@ -0,0 +1,41 @@
+---
+id: document-template
+title: document-template
+domain: development
+category: 00-governance
+difficulty: intermediate
+tags: [development, document, template, 失败模式, 执行步骤, 检查清单, 目标, 适用范围]
+quality_score: 70
+last_updated: 2026-06-15
+---
+# 开发：Excellent（11964948@qq.com）
+
+```yaml
+id: KB-DEV-XXXX
+title: 标题
+domain: development
+topic: 主题
+asset_type: standard
+owner: owner_name
+reviewers: [reviewer_name]
+status: draft
+version: v1.0
+created_at: 2026-03-06
+updated_at: 2026-03-06
+tags: [development, topic]
+summary: 用一句话说明条目价值
+```
+
+## 目标
+
+## 适用范围
+
+## 执行步骤
+
+## 检查清单
+
+## 验收标准
+
+## 失败模式
+
+## 回滚/替代策略

package/development/01-standards/api-versioning-strategies.md

@@ -0,0 +1,432 @@
+---
+id: api-versioning-strategies
+title: API版本控制策略
+domain: development
+category: 01-standards
+difficulty: intermediate
+tags: [agent, api, checklist, development, strategies, versioning, 实战代码示例, 常见陷阱]
+quality_score: 70
+last_updated: 2026-06-15
+---
+# API版本控制策略
+
+## 概述
+API版本控制是后端服务演进的关键策略。错误的版本策略会导致客户端大面积中断或永远无法清理遗留代码。本指南覆盖URL/Header/Query/Content-Type四种版本模式,并提供实战案例、迁移方案和废弃流程。
+
+## 核心概念
+
+### 1. 为什么需要版本控制
+- 向后不兼容的变更(Breaking Changes)需要版本隔离
+- 不同客户端(移动端/Web/合作方)可能需要不同版本
+- 平滑过渡:新版本上线时旧客户端不受影响
+- 废弃管理:有序引导客户端迁移
+
+### 2. 版本控制策略对比
+
+| 策略 | 格式 | 优势 | 劣势 | 代表 |
+|------|------|------|------|------|
+| URL路径 | `/api/v1/users` | 直观、缓存友好 | URL变动大、路由复杂 | Twitter/GitHub |
+| 请求头 | `API-Version: 2` | URL不变、灵活 | 不直观、调试难 | GitHub(也支持) |
+| 查询参数 | `?version=2` | 简单、可选 | 缓存键复杂、不规范 | Google Maps |
+| Content-Type | `Accept: application/vnd.api.v2+json` | HTTP语义正确 | 复杂、客户端支持差 | GitHub |
+| 日期版本 | `API-Version: 2024-01-15` | 渐进变更、精确 | 管理复杂 | Stripe |
+
+### 3. 什么是Breaking Change
+- 移除字段或端点
+- 重命名字段
+- 更改字段类型(string→number)
+- 更改默认行为
+- 更改错误码含义
+- 更改认证机制
+
+### 4. 什么不是Breaking Change
+- 添加新的可选字段
+- 添加新的端点
+- 添加新的可选查询参数
+- 添加新的响应头
+- 修复明显的Bug
+
+## 实战代码示例
+
+### URL路径版本(推荐首选)
+
+```python
+# FastAPI — URL路径版本
+from fastapi import FastAPI, APIRouter
+
+app = FastAPI()
+
+# V1路由
+v1_router = APIRouter(prefix="/api/v1", tags=["v1"])
+
+@v1_router.get("/users/{user_id}")
+async def get_user_v1(user_id: int):
+    """V1: 返回基础用户信息"""
+    user = await fetch_user(user_id)
+    return {
+        "id": user.id,
+        "name": user.name,
+        "email": user.email,
+    }
+
+# V2路由 — 增加了profile字段,重命名了name为full_name
+v2_router = APIRouter(prefix="/api/v2", tags=["v2"])
+
+@v2_router.get("/users/{user_id}")
+async def get_user_v2(user_id: int):
+    """V2: 返回完整用户信息(Breaking: name→full_name)"""
+    user = await fetch_user(user_id)
+    return {
+        "id": user.id,
+        "full_name": user.full_name,  # 重命名
+        "email": user.email,
+        "profile": {                   # 新增
+            "avatar_url": user.avatar_url,
+            "bio": user.bio,
+        },
+        "created_at": user.created_at.isoformat(),
+    }
+
+app.include_router(v1_router)
+app.include_router(v2_router)
+```
+
+```python
+# Django REST Framework — URL路径版本
+# urls.py
+from django.urls import path, include
+
+urlpatterns = [
+    path('api/v1/', include('api.v1.urls')),
+    path('api/v2/', include('api.v2.urls')),
+]
+
+# api/v1/views.py
+class UserViewSetV1(viewsets.ReadOnlyModelViewSet):
+    serializer_class = UserSerializerV1
+    queryset = User.objects.all()
+
+# api/v2/views.py
+class UserViewSetV2(viewsets.ModelViewSet):
+    serializer_class = UserSerializerV2
+    queryset = User.objects.select_related('profile').all()
+```
+
+### Header版本
+
+```python
+# FastAPI — Header版本
+from fastapi import Header, HTTPException
+
+@app.get("/api/users/{user_id}")
+async def get_user(
+    user_id: int,
+    api_version: str = Header(default="1", alias="API-Version")
+):
+    user = await fetch_user(user_id)
+
+    if api_version == "1":
+        return {"id": user.id, "name": user.name, "email": user.email}
+    elif api_version == "2":
+        return {
+            "id": user.id,
+            "full_name": user.full_name,
+            "email": user.email,
+            "profile": {"avatar_url": user.avatar_url},
+        }
+    else:
+        raise HTTPException(status_code=400, detail=f"Unsupported API version: {api_version}")
+```
+
+```javascript
+// Express.js — Header版本中间件
+function versionMiddleware(req, res, next) {
+  const version = req.headers['api-version'] || '1';
+  const supported = ['1', '2', '3'];
+
+  if (!supported.includes(version)) {
+    return res.status(400).json({
+      error: `Unsupported API version: ${version}`,
+      supported_versions: supported,
+    });
+  }
+
+  req.apiVersion = parseInt(version);
+  next();
+}
+
+app.use('/api', versionMiddleware);
+
+app.get('/api/users/:id', async (req, res) => {
+  const user = await getUser(req.params.id);
+
+  if (req.apiVersion === 1) {
+    return res.json({ id: user.id, name: user.name });
+  }
+  if (req.apiVersion >= 2) {
+    return res.json({ id: user.id, fullName: user.fullName, profile: user.profile });
+  }
+});
+```
+
+### Stripe风格日期版本(高级)
+
+```python
+# 日期版本策略 — 每个API变更关联一个日期
+from datetime import date
+from functools import wraps
+from typing import Callable
+
+# 版本变更注册表
+VERSION_CHANGES = {
+    "2024-01-15": {
+        "description": "Rename name to full_name in User response",
+        "transformer": "transform_user_v20240115",
+    },
+    "2024-06-01": {
+        "description": "Add pagination metadata wrapper",
+        "transformer": "transform_pagination_v20240601",
+    },
+    "2025-01-01": {
+        "description": "Remove deprecated email_verified field",
+        "transformer": "transform_user_v20250101",
+    },
+}
+
+LATEST_VERSION = "2025-01-01"
+
+def apply_version_transforms(response: dict, requested_version: str) -> dict:
+    """按时间顺序反向应用变更,将最新响应降级为请求版本"""
+    changes = sorted(VERSION_CHANGES.keys(), reverse=True)
+
+    for change_date in changes:
+        if change_date > requested_version:
+            # 应用反向变换
+            transformer = get_transformer(VERSION_CHANGES[change_date]["transformer"])
+            response = transformer.downgrade(response)
+
+    return response
+
+@app.get("/api/users/{user_id}")
+async def get_user(
+    user_id: int,
+    api_version: str = Header(default=LATEST_VERSION, alias="Stripe-Version")
+):
+    """始终用最新逻辑获取数据,然后按版本降级响应"""
+    user = await fetch_user_latest(user_id)
+    response = serialize_user_latest(user)
+    return apply_version_transforms(response, api_version)
+```
+
+### Content-Type协商版本
+
+```python
+# Accept头版本
+from fastapi import Request, HTTPException
+
+@app.get("/api/users/{user_id}")
+async def get_user(user_id: int, request: Request):
+    accept = request.headers.get("accept", "application/json")
+
+    if "application/vnd.myapi.v2+json" in accept:
+        return await get_user_v2(user_id)
+    elif "application/vnd.myapi.v1+json" in accept:
+        return await get_user_v1(user_id)
+    else:
+        # 默认最新版本
+        return await get_user_v2(user_id)
+```
+
+### 版本废弃通知
+
+```python
+# 废弃中间件 — 添加Deprecation/Sunset响应头
+from starlette.middleware.base import BaseHTTPMiddleware
+from datetime import datetime
+
+DEPRECATED_VERSIONS = {
+    "v1": {
+        "deprecated_at": "2024-06-01",
+        "sunset_at": "2025-06-01",
+        "migration_guide": "https://docs.example.com/migration/v1-to-v2",
+    },
+}
+
+class DeprecationMiddleware(BaseHTTPMiddleware):
+    async def dispatch(self, request, call_next):
+        response = await call_next(request)
+
+        # 从URL提取版本
+        path = request.url.path
+        for version, info in DEPRECATED_VERSIONS.items():
+            if f"/api/{version}/" in path:
+                response.headers["Deprecation"] = info["deprecated_at"]
+                response.headers["Sunset"] = info["sunset_at"]
+                response.headers["Link"] = (
+                    f'<{info["migration_guide"]}>; rel="deprecation"'
+                )
+                # 可选: 记录使用废弃API的客户端
+                client_id = request.headers.get("X-Client-ID", "unknown")
+                logger.warning(
+                    "Deprecated API usage",
+                    extra={"version": version, "client_id": client_id, "path": path}
+                )
+                break
+
+        return response
+
+app.add_middleware(DeprecationMiddleware)
+```
+
+### 客户端SDK版本适配
+
+```typescript
+// TypeScript客户端 — 版本化API调用
+interface ApiClientOptions {
+  baseUrl: string;
+  version: 'v1' | 'v2';
+  apiKey: string;
+}
+
+class ApiClient {
+  constructor(private options: ApiClientOptions) {}
+
+  private get headers() {
+    return {
+      'Authorization': `Bearer ${this.options.apiKey}`,
+      'API-Version': this.options.version.replace('v', ''),
+      'Content-Type': 'application/json',
+    };
+  }
+
+  async getUser(userId: number): Promise<UserV1 | UserV2> {
+    const res = await fetch(
+      `${this.options.baseUrl}/api/${this.options.version}/users/${userId}`,
+      { headers: this.headers }
+    );
+
+    if (!res.ok) throw new ApiError(res);
+
+    // 检查废弃警告
+    const sunset = res.headers.get('Sunset');
+    if (sunset) {
+      console.warn(`API ${this.options.version} will be sunset on ${sunset}`);
+    }
+
+    return res.json();
+  }
+}
+```
+
+## 最佳实践
+
+### 1. 选型建议
+- **公开API(第三方开发者)**: URL路径版本 — 最直观、最易文档化
+- **内部微服务**: Header版本 — URL不变,服务发现不受影响
+- **频繁迭代的SaaS API**: 日期版本(Stripe模式) — 细粒度控制
+- **避免使用**: 查询参数版本 — 不够规范,容易遗忘
+
+### 2. 版本生命周期
+- **Active**: 当前推荐版本,全功能支持
+- **Deprecated**: 仍可用但不推荐,添加Deprecation头
+- **Sunset**: 关闭倒计时,返回Sunset头和迁移链接
+- **Retired**: 停止服务,返回410 Gone
+
+### 3. 迁移友好设计
+- 废弃前至少提前6个月通知
+- 提供迁移指南文档
+- 提供版本差异对比工具
+- SDK自动发出废弃警告
+- 监控各版本使用量,确认无流量后再关闭
+
+### 4. 减少版本数
+- 添加新字段不算Breaking Change,不需要新版本
+- 使用可选参数扩展而非创建新版本
+- 最多同时维护2-3个版本
+- 定期合并清理旧版本代码
+
+### 5. 文档规范
+- 每个版本有独立文档页面
+- 变更日志清晰标注Breaking Changes
+- 迁移指南提供前后对比代码
+
+## 常见陷阱
+
+### 陷阱1: 内部共享模型导致版本耦合
+```python
+# 错误: V1和V2共享同一个数据模型
+class UserModel:
+    name: str  # V1用name, V2要用full_name
+
+# 正确: 每个版本独立的Response Schema
+class UserResponseV1(BaseModel):
+    name: str
+    email: str
+
+class UserResponseV2(BaseModel):
+    full_name: str
+    email: str
+    profile: ProfileSchema
+```
+
+### 陷阱2: 忘记版本化错误格式
+```python
+# 错误: 只版本化了正常响应,错误格式改了导致客户端解析崩溃
+# V1: {"error": "not found"}
+# V2: {"errors": [{"code": "NOT_FOUND", "message": "not found"}]}
+
+# 正确: 错误格式也纳入版本控制
+```
+
+### 陷阱3: 永远不删除旧版本
+```python
+# 错误: 积累了v1到v8共8个版本,每个版本都有独立代码
+# 正确: 制定明确的Sunset策略,最多维护3个版本
+# 使用数据驱动决策: 旧版本流量<1%时启动Sunset流程
+```
+
+### 陷阱4: 在URL中使用minor/patch版本
+```
+# 错误
+/api/v1.2.3/users  — 版本变动太频繁
+
+# 正确
+/api/v1/users      — 只用major版本
+/api/v2/users
+```
+
+### 陷阱5: 默认版本不一致
+```python
+# 错误: 不同端点默认不同版本
+# /api/users — 默认v2
+# /api/orders — 默认v1
+
+# 正确: 全局统一默认版本策略
+DEFAULT_API_VERSION = "2"
+```
+
+## Agent Checklist
+
+### 版本策略设计
+- [ ] 选择了合适的版本控制方式(URL/Header/日期)
+- [ ] 定义了Breaking Change的判断标准
+- [ ] 制定了版本生命周期策略(Active/Deprecated/Sunset/Retired)
+- [ ] 明确了最大同时维护版本数
+
+### 实现规范
+- [ ] 每个版本有独立的Request/Response Schema
+- [ ] 错误格式纳入版本控制
+- [ ] 废弃版本添加Deprecation/Sunset响应头
+- [ ] 版本信息包含在日志和监控指标中
+
+### 客户端友好
+- [ ] 提供版本变更日志
+- [ ] 提供迁移指南和代码示例
+- [ ] SDK/客户端库自动输出废弃警告
+- [ ] 默认版本策略清晰文档化
+
+### 运维管理
+- [ ] 监控各版本API使用量和客户端分布
+- [ ] Sunset前确认无残留流量
+- [ ] 旧版本代码和测试定期清理
+- [ ] CI/CD覆盖所有活跃版本的测试