---
title: vendor 设计与规范
description: WWJCloud 框架的第三方外设适配层（vendor）定位、目录规范、依赖关系、SaaS 按站点解析与可扩展策略。
---

## vendor 的定位与边界
- 角色: 外设适配层（Third-party Adapters），承载与厂商/外部系统交互的所有实现（存储、支付、短信、HTTP 等）。
- 边界:
  - 不承载业务逻辑；不直接被 `controllers` 调用。
  - 通过 Token/接口注入给上层（common/app）的 Infrastructure 或 Application。
  - 与 `core` 的关系: core 提供底座（事件/队列/事务/观测/配置校验），vendor 提供具体厂商实现与可配置模块。

## 架构依赖
- 依赖方向: App → Common → Core → Vendor（单向）
- vendor 不得反向依赖 `app/common`；配置/健康/观测由 `core` 聚合。

## 目录规范（以存储为例，其他能力同构）
```
vendor/storage/
├── index.ts                     # 统一导出(接口、Token、模块、适配器)
├── storage.module.ts            # 可配置模块(选择具体实现)
├── tokens.ts                    # 注入Token常量(如 STORAGE_ADAPTER)
├── interfaces/
│   ├── storage-adapter.ts       # 适配器接口(平台契约)
│   └── types.ts                 # 通用类型
├── adapters/
│   ├── local.adapter.ts         # 本地实现
│   ├── aliyun-oss.adapter.ts    # 阿里云实现
│   ├── qcloud-cos.adapter.ts    # 腾讯云实现
│   └── qiniu.adapter.ts         # 七牛云实现
├── providers/
│   ├── storage.provider.ts      # 工厂: 按配置/站点解析适配器
│   └── registry.ts              # 多实例注册表 Map<siteId, adapter> + TTL
├── health/storage.health.ts     # 健康检查(各实现可选实现)
├── config/schema.ts             # 配置Schema(必需项校验)
└── __tests__/
    ├── storage.contract.spec.ts # 契约测试(接口一致性)
    └── adapters/*.spec.ts       # 各实现最小测试
```

## SaaS 按站点(site_id)解析
- 优先级: 站点启用 > 跟随系统(平台默认) > 兜底 local（强制 `upload/site_{siteId}/...` 路径隔离）。
- 解析工厂:
```ts
function resolveAdapter(siteId: number): StorageAdapter {
  const enabled = readSiteEnabled(siteId);      // storage_xxx with is_use
  const type = enabled?.type ?? readPlatformDefault();
  const options = enabled?.options ?? readPlatformOptions(type) ?? {};
  return registry.getOrCreate(siteId, type, options);
}
```
- 健康: 对活跃站点适配器定期 `healthCheck()`；并聚合到 `core/health`。

## 设计理念（三条）
- 外设即插件: 能力以模块化/可插拔形式提供（storage/payment/sms/http/...）。
- 接口优先: 先接口与契约测试，后接入厂商 SDK，保证可替换性。
- 多租原生: 所有适配器必须支持 `site_id` 维度的实例解析与隔离。

## 配置与版本
- 配置来源: `sys_config.value(JSON)` + `.env`；装载时 Schema 校验，不通过则阻断启动。
- 版本策略: 适配器遵循 SemVer；接口变更以主版本升级并附迁移指南。

## 契约测试（强制）
- 每个能力的接口附带 `contract.spec`；所有适配器实现必须通过（例如 storage 的 upload/delete/signUpload 一致性）。
- 在 CI 的 QualityGate 阶段与 e2e 一并纳入。

## 可扩展性（接入新厂商）
- 流程: 生成骨架 → `adapters/*.adapter.ts` → 增加 `config/schema.ts` → 注册工厂分支 → 补 `__tests__/contract.spec.ts` 与健康探针。
- 脚手架: 规划提供 `pnpm dlx` 子命令生成适配器骨架。

## 与 core 的协作
- 观测: 通过 `core/observability` 输出 trace/metrics/log 标签（厂商/站点/区域）。
- 队列与事件: 业务在 Application 层入队/发事件，vendor 不持有业务编排。
- 配置: 由 `core/config` 校验与注入，vendor 仅消费配置。

> 说明: 若未来需要跨仓/多微服务统一技术端口，可将“接口定义”上移至 `core`（A+B），实现仍在 `vendor`，老业务无感升级。 