Kris
6dd16ad3f8
本次提交对多个外部系统路由进行了多维度优化： 1. 统一分页参数：将所有路由的`page = offset//limit +1`、`page_size=limit`替换为标准的`limit`+`offset`分页格式 2. 完善接口文档：补充多个端点的功能说明、参数含义与返回字段解释 3. 增强参数校验：新增字段长度限制、正则校验、枚举类型约束与业务逻辑校验 4. 优化代码复用：提取重复逻辑为辅助函数，减少样板代码 5. 修复接口问题：修正工具健康检查端点路径参数类型，优化导出接口响应格式 6. 补充异常处理：为批量操作添加异常捕获与日志记录，避免流程中断
389 lines
16 KiB
Python
389 lines
16 KiB
Python
"""Adapter 子域 Router。
|
||
|
||
外部系统限界上下文的适配器元数据查询 API。元数据查询端点直接读取
|
||
``default_registry`` 全局单例；运行时统计端点通过
|
||
``create_adapter_stats_service_from_db`` 轻量工厂注入
|
||
``AdapterStatsService``（仅需 Repositories，无需构造完整 24-service
|
||
UseCases 容器），调用 ``adapter_stats_service`` 聚合系统/工具/资产/指标/健康数据。
|
||
|
||
设计依据：docs/vibe/v1.1/设计方案/RouterAPI扩展设计/03-adapter_router扩展设计方案.md
|
||
"""
|
||
|
||
from __future__ import annotations
|
||
|
||
from datetime import datetime
|
||
from types import SimpleNamespace
|
||
from typing import Any
|
||
|
||
from fastapi import APIRouter, Depends, Query
|
||
from pydantic import BaseModel, ValidationError
|
||
from sqlalchemy.ext.asyncio import AsyncSession
|
||
from yuxi.external_systems.exceptions import (
|
||
CapabilityNotSupportedError,
|
||
DomainValidationError,
|
||
)
|
||
from yuxi.external_systems.framework.auth_plugins import (
|
||
get_auth_json_schema,
|
||
get_auth_json_schemas,
|
||
is_token_based_auth_type,
|
||
list_auth_plugins,
|
||
)
|
||
from yuxi.external_systems.framework.auth_plugins.protocol_registry import (
|
||
list_protocol_auth_plugins,
|
||
)
|
||
from yuxi.external_systems.framework.registry.adapter_registry import default_registry
|
||
from yuxi.external_systems.infrastructure.container import (
|
||
create_adapter_stats_service_from_db,
|
||
)
|
||
from yuxi.external_systems.use_cases.dto.adapter_stats import (
|
||
GetAdapterHealthInput,
|
||
GetAdapterStatsInput,
|
||
)
|
||
from yuxi.storage.postgres.models_business import User
|
||
|
||
from server.utils.auth_middleware import get_admin_user, get_db, get_required_user
|
||
|
||
# =============================================================================
|
||
# === Request Schemas ===
|
||
# =============================================================================
|
||
|
||
|
||
class ValidateConfigRequest(BaseModel):
|
||
"""适配器配置校验请求体。"""
|
||
|
||
config: dict[str, Any]
|
||
|
||
|
||
adapter_router = APIRouter(
|
||
prefix="/adapters",
|
||
tags=["external-systems-adapter"],
|
||
)
|
||
|
||
|
||
# =============================================================================
|
||
# === 静态路径端点（必须在 /{adapter_type} 之前声明） ===
|
||
# =============================================================================
|
||
|
||
|
||
@adapter_router.get("", response_model=dict)
|
||
async def list_adapters(
|
||
current_user: User = Depends(get_required_user),
|
||
) -> dict[str, Any]:
|
||
"""列出所有已注册的适配器类型（按字母序排序，保证 API 响应稳定性）。"""
|
||
adapters = sorted(default_registry.list_adapter_types())
|
||
return {"success": True, "data": {"items": adapters, "total": len(adapters)}}
|
||
|
||
|
||
@adapter_router.get("/overview", response_model=dict)
|
||
async def get_adapters_overview(
|
||
current_user: User = Depends(get_required_user),
|
||
) -> dict[str, Any]:
|
||
"""查询所有已注册适配器的元数据总览（按 adapter_type 排序）。
|
||
|
||
返回每个适配器的展示信息、能力、认证类型、数据源类型与 category_prefix，
|
||
不包含 config_schema / connection_schema / auth_schemas（避免响应过重）。
|
||
适合前端适配器市场页一次性渲染卡片。
|
||
"""
|
||
metadata_list = sorted(
|
||
default_registry.list_adapter_metadata(),
|
||
key=lambda m: m.adapter_type,
|
||
)
|
||
items = [
|
||
{
|
||
"adapter_type": metadata.adapter_type,
|
||
"display_name": metadata.display_name,
|
||
"description": metadata.description,
|
||
"capabilities": metadata.to_capabilities(),
|
||
"supported_auth_types": metadata.supported_auth_types,
|
||
"supported_source_types": metadata.supported_source_types,
|
||
"category_prefix": metadata.category_prefix,
|
||
}
|
||
for metadata in metadata_list
|
||
]
|
||
return {"success": True, "data": {"items": items, "total": len(items)}}
|
||
|
||
|
||
# =============================================================================
|
||
# === 路径参数端点（/{adapter_type}） ===
|
||
# =============================================================================
|
||
|
||
|
||
@adapter_router.get("/{adapter_type}", response_model=dict)
|
||
async def get_adapter(
|
||
adapter_type: str,
|
||
current_user: User = Depends(get_required_user),
|
||
) -> dict[str, Any]:
|
||
"""获取适配器详情，包含展示信息、配置/连接 Schema、能力声明、资产类型与认证 Schema。
|
||
|
||
作为 overview 的超集，额外返回 config_schema / connection_schema /
|
||
asset_types / auth_schemas，并补全 category_prefix 与 supported_auth_types，
|
||
确保 detail 端点字段覆盖度 >= overview 端点。
|
||
|
||
``AdapterMetadata.config_schema`` / ``connection_schema`` 是 Pydantic 模型类
|
||
（非实例），无法直接序列化，故通过 ``to_json_schema()`` / ``to_connection_json_schema()``
|
||
单独提供其 JSON Schema。``AdapterNotFoundError`` 由全局处理器映射为 404。
|
||
"""
|
||
metadata = default_registry.get_adapter_metadata(adapter_type)
|
||
data = {
|
||
"adapter_type": metadata.adapter_type,
|
||
"display_name": metadata.display_name,
|
||
"description": metadata.description,
|
||
"category_prefix": metadata.category_prefix,
|
||
"config_schema": metadata.to_json_schema(),
|
||
"connection_schema": metadata.to_connection_json_schema(),
|
||
"capabilities": metadata.to_capabilities(),
|
||
"asset_types": metadata.to_asset_types(),
|
||
"supported_auth_types": metadata.supported_auth_types,
|
||
"auth_schemas": get_auth_json_schemas(
|
||
metadata.supported_auth_types,
|
||
adapter_type=metadata.adapter_type,
|
||
),
|
||
"supported_source_types": metadata.supported_source_types,
|
||
}
|
||
return {"success": True, "data": data}
|
||
|
||
|
||
@adapter_router.get("/{adapter_type}/capabilities", response_model=dict)
|
||
async def get_adapter_capabilities(
|
||
adapter_type: str,
|
||
current_user: User = Depends(get_required_user),
|
||
) -> dict[str, Any]:
|
||
"""查询适配器支持的能力（轻量端点，仅返回 5 个能力字段）。
|
||
|
||
与详情端点的差异：详情端点返回完整元数据（含 Schema 与资产类型），
|
||
本端点仅返回 ``to_capabilities()`` 的 5 个能力字段，响应体减小约 80%。
|
||
``AdapterNotFoundError`` 由全局处理器映射为 404。
|
||
"""
|
||
metadata = default_registry.get_adapter_metadata(adapter_type)
|
||
return {"success": True, "data": metadata.to_capabilities()}
|
||
|
||
|
||
@adapter_router.get("/{adapter_type}/config-schema", response_model=dict)
|
||
async def get_adapter_config_schema(
|
||
adapter_type: str,
|
||
current_user: User = Depends(get_required_user),
|
||
) -> dict[str, Any]:
|
||
"""获取适配器配置与连接配置的 JSON Schema，用于前端动态表单渲染。
|
||
|
||
与详情端点的差异：详情端点的 config_schema / connection_schema 与其他元数据混合，
|
||
本端点仅返回 Schema，适合前端表单渲染时独立获取。
|
||
``AdapterNotFoundError`` 由全局处理器映射为 404。
|
||
"""
|
||
metadata = default_registry.get_adapter_metadata(adapter_type)
|
||
data = {
|
||
"config_schema": metadata.to_json_schema(),
|
||
"connection_schema": metadata.to_connection_json_schema(),
|
||
}
|
||
return {"success": True, "data": data}
|
||
|
||
|
||
@adapter_router.get("/{adapter_type}/auth-plugins", response_model=dict)
|
||
async def get_adapter_auth_plugins(
|
||
adapter_type: str,
|
||
current_user: User = Depends(get_required_user),
|
||
) -> dict[str, Any]:
|
||
"""查询适配器支持的认证插件清单（含框架级 + 协议专属）。
|
||
|
||
过滤逻辑：``list_auth_plugins`` 返回全部框架级插件 + 协议专属插件，
|
||
但适配器仅声明支持 ``supported_auth_types`` 中的框架级认证类型。此处
|
||
按 ``metadata.supported_auth_types`` 过滤框架级插件，同时保留全部协议
|
||
专属插件（协议专属插件由适配器层自注册，天然属于该适配器）。
|
||
|
||
Schema 获取：``get_auth_json_schema`` 对 ``credential_type=None`` 的插件
|
||
抛 ``DomainValidationError``，此处捕获并返回 ``None``，避免单个无凭证类型
|
||
的插件导致整个端点 500。
|
||
|
||
与详情端点的差异：详情端点通过 ``get_auth_json_schemas()`` 仅返回
|
||
``{auth_type: schema}`` 字典，本端点额外返回 display_name 与 is_token_based，
|
||
适合前端认证方式选择下拉框渲染。
|
||
``AdapterNotFoundError`` 由全局处理器映射为 404。
|
||
"""
|
||
metadata = default_registry.get_adapter_metadata(adapter_type)
|
||
|
||
# 协议专属插件类型集合（天然属于该适配器，无需过滤）
|
||
protocol_types = {p["type"] for p in list_protocol_auth_plugins(adapter_type)}
|
||
# 框架级插件按 supported_auth_types 过滤
|
||
supported_set = set(metadata.supported_auth_types)
|
||
all_plugins = list_auth_plugins(adapter_type=adapter_type)
|
||
filtered_plugins = [p for p in all_plugins if p["type"] in supported_set or p["type"] in protocol_types]
|
||
|
||
items = []
|
||
for plugin in filtered_plugins:
|
||
try:
|
||
schema = get_auth_json_schema(plugin["type"], adapter_type=adapter_type)
|
||
except DomainValidationError:
|
||
# 插件 credential_type=None（如纯协议标记插件），无 JSON Schema
|
||
schema = None
|
||
items.append(
|
||
{
|
||
"type": plugin["type"],
|
||
"display_name": plugin["display_name"],
|
||
"schema": schema,
|
||
"is_token_based": is_token_based_auth_type(
|
||
plugin["type"],
|
||
adapter_type=adapter_type,
|
||
),
|
||
}
|
||
)
|
||
return {"success": True, "data": {"items": items, "total": len(items)}}
|
||
|
||
|
||
@adapter_router.get("/{adapter_type}/source-types", response_model=dict)
|
||
async def get_adapter_source_types(
|
||
adapter_type: str,
|
||
current_user: User = Depends(get_required_user),
|
||
) -> dict[str, Any]:
|
||
"""查询适配器支持的数据源类型（如 http 适配器的 openapi / postman / curl）。
|
||
|
||
响应字段名 ``supported_source_types`` 与 ``AdapterMetadata`` 字段名及
|
||
overview / detail 端点保持一致，避免命名碎片化。
|
||
|
||
``AdapterNotFoundError`` 由全局处理器映射为 404。
|
||
"""
|
||
metadata = default_registry.get_adapter_metadata(adapter_type)
|
||
data = {
|
||
"adapter_type": metadata.adapter_type,
|
||
"supported_source_types": metadata.supported_source_types,
|
||
}
|
||
return {"success": True, "data": data}
|
||
|
||
|
||
@adapter_router.get("/{adapter_type}/assets", response_model=dict)
|
||
async def get_adapter_assets(
|
||
adapter_type: str,
|
||
current_user: User = Depends(get_required_user),
|
||
) -> dict[str, Any]:
|
||
"""获取适配器资产信息，包含资产类型列表、示例配置与资产生成能力。
|
||
|
||
``asset_type_descriptions`` / ``example_config`` 为 None 时默认返回空值
|
||
（``{}``），避免前端需额外处理 None 分支。
|
||
|
||
``AdapterNotFoundError`` 由全局处理器映射为 404。
|
||
"""
|
||
metadata = default_registry.get_adapter_metadata(adapter_type)
|
||
data = {
|
||
"adapter_type": metadata.adapter_type,
|
||
"asset_types": metadata.to_asset_types(),
|
||
"asset_type_descriptions": metadata.asset_type_descriptions or {},
|
||
"example_config": metadata.example_config or {},
|
||
"supports_asset_generation": metadata.supports_asset_generation,
|
||
}
|
||
return {"success": True, "data": data}
|
||
|
||
|
||
@adapter_router.post("/{adapter_type}/validate-config", response_model=dict)
|
||
async def validate_adapter_config(
|
||
adapter_type: str,
|
||
body: ValidateConfigRequest,
|
||
current_user: User = Depends(get_admin_user),
|
||
) -> dict[str, Any]:
|
||
"""校验适配器配置是否符合 Schema（不实际执行，仅校验）。
|
||
|
||
调用适配器实例的 ``validate_config`` 可选能力。适配器未实现该能力时
|
||
抛 Python 内置 ``NotImplementedError``，Router 内翻译为
|
||
``CapabilityNotSupportedError`` 交由 ``unified_error_handler`` 统一映射
|
||
为 HTTP 501，避免原生异常被兜底为 500。
|
||
|
||
``SimpleNamespace`` 构造说明：``validate_config`` 签名仅接受
|
||
``ExecutableTool``，其中 ``adapter_config`` 是校验目标（来自请求体），
|
||
其余字段（slug / name / auth_type 等）对配置校验无语义影响，使用
|
||
合理默认值填充以满足 Protocol 结构契约。
|
||
|
||
``AdapterNotFoundError`` 由全局处理器映射为 404。
|
||
"""
|
||
adapter = default_registry.get_adapter(adapter_type)
|
||
|
||
# 构造 ExecutableTool 兼容对象（SimpleNamespace 严格对齐 Protocol 的 12 个字段）
|
||
# validate_config 仅消费 tool.adapter_config，其余字段用安全默认值填充
|
||
tool = SimpleNamespace(
|
||
slug="",
|
||
name="",
|
||
description="",
|
||
adapter_type=adapter_type,
|
||
auth_type="none",
|
||
adapter_config=body.config,
|
||
auth_config={},
|
||
timeout=30,
|
||
retry_policy={},
|
||
enabled=True,
|
||
system_id=None,
|
||
id=None,
|
||
)
|
||
|
||
try:
|
||
await adapter.validate_config(tool) # type: ignore[attr-defined]
|
||
except NotImplementedError as exc:
|
||
# 适配器未实现配置校验能力，翻译为 CapabilityNotSupportedError，
|
||
# 交由 unified_error_handler 统一映射为 HTTP 501，保留原始 traceback。
|
||
raise CapabilityNotSupportedError(
|
||
capability="validate_config",
|
||
adapter_type=adapter_type,
|
||
) from exc
|
||
except ValidationError as exc:
|
||
# Pydantic 校验失败，返回 200 + valid=False（业务校验结果，非请求体格式错误）
|
||
# errors 格式化为 list[str]，与 auth_plugin_router / system_router 校验端点对齐
|
||
return {
|
||
"success": True,
|
||
"data": {
|
||
"valid": False,
|
||
"errors": [f"{'.'.join(str(p) for p in e['loc'])}: {e['msg']}" for e in exc.errors()],
|
||
},
|
||
}
|
||
|
||
return {"success": True, "data": {"valid": True, "errors": []}}
|
||
|
||
|
||
# =============================================================================
|
||
# === 运行时统计端点（轻量工厂注入 adapter_stats_service） ===
|
||
# =============================================================================
|
||
|
||
|
||
@adapter_router.get("/{adapter_type}/stats", response_model=dict)
|
||
async def get_adapter_stats(
|
||
adapter_type: str,
|
||
start_time: datetime | None = Query(None, description="指标聚合起始时间"),
|
||
end_time: datetime | None = Query(None, description="指标聚合结束时间"),
|
||
current_user: User = Depends(get_required_user),
|
||
db: AsyncSession = Depends(get_db),
|
||
) -> dict[str, Any]:
|
||
"""查询适配器维度的使用统计（系统数 / 工具数 / 资产数 / 指标聚合）。
|
||
|
||
先通过 ``get_adapter_metadata`` 校验适配器存在（抛 ``AdapterNotFoundError`` → 404），
|
||
再通过轻量工厂 ``create_adapter_stats_service_from_db`` 创建
|
||
``AdapterStatsService``（仅注入 Repositories，不构造完整 UseCases 容器）。
|
||
``start_time`` / ``end_time`` 仅作用于指标聚合，不影响系统/工具/资产计数。
|
||
"""
|
||
# 校验适配器存在（抛 AdapterNotFoundError → 404）
|
||
default_registry.get_adapter_metadata(adapter_type)
|
||
|
||
stats_service = create_adapter_stats_service_from_db(db)
|
||
input_dto = GetAdapterStatsInput(
|
||
adapter_type=adapter_type,
|
||
start=start_time,
|
||
end=end_time,
|
||
)
|
||
output = await stats_service.get_adapter_stats(input_dto)
|
||
return {"success": True, "data": output.model_dump()}
|
||
|
||
|
||
@adapter_router.get("/{adapter_type}/health", response_model=dict)
|
||
async def get_adapter_health(
|
||
adapter_type: str,
|
||
current_user: User = Depends(get_required_user),
|
||
db: AsyncSession = Depends(get_db),
|
||
) -> dict[str, Any]:
|
||
"""查询适配器维度的健康状态（基于关联系统最近一次健康检查聚合）。
|
||
|
||
先通过 ``get_adapter_metadata`` 校验适配器存在（抛 ``AdapterNotFoundError`` → 404），
|
||
再通过轻量工厂 ``create_adapter_stats_service_from_db`` 创建
|
||
``AdapterStatsService``（仅注入 Repositories，不构造完整 UseCases 容器）。
|
||
``status`` 取值：unknown / healthy / degraded / unhealthy（见 DTO docstring）。
|
||
"""
|
||
# 校验适配器存在（抛 AdapterNotFoundError → 404）
|
||
default_registry.get_adapter_metadata(adapter_type)
|
||
|
||
stats_service = create_adapter_stats_service_from_db(db)
|
||
input_dto = GetAdapterHealthInput(adapter_type=adapter_type)
|
||
output = await stats_service.get_adapter_health(input_dto)
|
||
return {"success": True, "data": output.model_dump()}
|