3.0 KiB

Raw Permalink Blame History

Jointo Tech Stack Skill 架构更新

日期: 2026-01-31
类型: 文档更新
影响范围: .claude/skills/jointo-tech-stack/references/backend.md

背景

在完成 AI Provider 架构简化后（删除 app/clients/ 目录），需要同步更新 jointo-tech-stack skill 文档，确保架构描述与实际代码一致。

变更内容

1. 更新架构层次

之前：四层架构

API 层 → Service 层 → Provider 层 → Client 层

现在：三层架构

API 层 → Service 层 → Provider 层（直接使用 SDK 或 httpx）

2. 删除 Client 层相关内容

❌ 删除项目结构中的 app/clients/ 目录
❌ 删除 BaseHTTPClient 相关示例
❌ 删除 Client 层测试示例

3. 更新架构原则

添加明确的架构原则：

**架构原则**：
- ✅ 有官方 SDK：Provider 直接使用 SDK
- ⚠️ 无官方 SDK：Provider 使用 `httpx.AsyncClient`
- ❌ 不要创建独立的 Client 层（避免过度设计）

4. 更新代码示例

新增 AI 厂商示例

使用官方 SDK：

from openai import AsyncOpenAI

class AIHubMixProvider(BaseAIProvider):
    def __init__(self, model_name: str, config: Optional[Dict] = None):
        super().__init__(model_name, config)
        self.client = AsyncOpenAI(
            api_key=settings.AIHUBMIX_API_KEY,
            base_url=settings.AIHUBMIX_BASE_URL
        )

无官方 SDK：

import httpx

class MyAIProvider(BaseAIProvider):
    def __init__(self, model_name: str, config: Optional[Dict] = None):
        super().__init__(model_name, config)
        self.client = httpx.AsyncClient(
            base_url=settings.MY_AI_BASE_URL,
            headers={"Authorization": f"Bearer {settings.MY_AI_API_KEY}"}
        )

更新最佳实践

✅ 优先使用官方 SDK
✅ Provider 层负责数据适配
✅ Service 层负责业务编排

更新错误处理

移除 Client 层错误处理示例
Provider 层统一处理 HTTP 和业务错误

更新测试示例

移除 Client 层测试
Provider 层测试直接测试 SDK 调用
使用 Mock 测试 Provider 层

修改的文件

✅ .claude/skills/jointo-tech-stack/references/backend.md
- 更新 AI Provider 架构章节
- 删除所有 Client 层引用
- 更新代码示例和最佳实践

验证

# 搜索是否还有 Client 层引用
grep -r "app/clients" .claude/skills/jointo-tech-stack/
grep -r "BaseHTTPClient" .claude/skills/jointo-tech-stack/
grep -r "Client 层" .claude/skills/jointo-tech-stack/

# 应该只返回架构说明中的"不再使用独立的 Client 层"

影响

✅ Skill 文档与实际代码架构一致
✅ 新开发者不会被误导创建 Client 层
✅ 明确了"优先使用官方 SDK"的原则

3.0 KiB Raw Permalink Blame History