---
title: 领域边界与接口/事件规范
description: 为单体向微服务平滑演进提供的领域边界、接口与事件契约、数据归属与最小 SDK 结构规范
---

# 领域边界与接口/事件规范

> 目标：先在单体内按微服务边界设计，后续可平滑替换为远程调用而不改业务层。

## 1. 领域划分与数据归属
- IAM（身份与访问）
  - 职责：认证（JWT/OAuth2）、用户目录、角色/权限、Token 签发与吊销、审计
  - 数据：users、roles、permissions、role_permission、user_role、audit_logs
  - 前缀：`/adminapi/iam/*`、`/api/iam/*`（仅示意）
- Member（会员）
  - 职责：会员账户、等级、积分/余额、地址管理
  - 数据：members、member_levels、member_points、member_balance、member_address
  - 前缀：`/api/member/*`、`/adminapi/member/*`
- Settings（系统设置）
  - 职责：站点、登录、存储、支付、短信、邮件等平台配置
  - 数据：settings_*（按配置域划分），只读缓存加速
  - 前缀：`/adminapi/settings/*`
- Upload（文件存储）
  - 职责：文件上传、存储策略、回源/签名、清理
  - 数据：files、file_buckets（或外部对象存储）
  - 前缀：`/upload/*`、`/adminapi/storage/*`
- Notification（通知中心）
  - 职责：邮件/短信/站内信模板与发送、事件触发
  - 数据：notification_templates、notification_logs
  - 前缀：`/adminapi/notice/*`
- Schedule（调度）
  - 职责：定时任务、启停、运行日志
  - 数据：schedules、schedule_logs
  - 前缀：`/adminapi/schedule/*`

原则：
- 严禁跨域直接查/写对方数据库；仅通过接口/事件交互。
- 每个域对外暴露“公开服务（Service API）与领域事件（Domain Events）”。

## 2. 服务接口（Service API）契约
- 通用规范
  - 认证：默认需要 JWT；内部调用可走服务账号或网关信任
  - 版本：路径或 Header 版本化（推荐路径，示例：`/api/v1/...`）
  - 错误：统一响应格式与错误码（已在 `openapi/standards/*` 约定）
  - 限流：由网关统一治理，服务端暴露必要的幂等键与速率提示

- IAM 示例
  - `POST /api/v1/iam/auth/login`（登录、签发 Access/Refresh）
  - `POST /api/v1/iam/auth/refresh`（刷新）
  - `GET  /api/v1/iam/users/me`（当前用户）
  - `GET  /api/v1/iam/permissions/check?resource=&action=`（权限判定）

- Member 示例
  - `GET  /api/v1/members/{id}`（查询会员）
  - `POST /api/v1/members`（创建）
  - `GET  /api/v1/members/{id}/points`（积分流水）

- Settings 示例
  - `GET  /adminapi/v1/settings/login`（读取登录设置）
  - `PUT  /adminapi/v1/settings/login`（更新登录设置）

- Upload 示例
  - `POST /upload/file`（直传）
  - `GET  /adminapi/v1/storage/health`（健康检查）

- Notification 示例
  - `POST /adminapi/v1/notice/send`（按模板发送）

- Schedule 示例
  - `GET  /adminapi/v1/schedule/list`（任务列表）

说明：
- 站内调用优先使用“域 SDK”（见第 5 节），后续可替换为 RPC/HTTP 实现。

## 3. 领域事件（Domain Events）
- 命名：`<Noun><Verb>ed`，如 `UserCreated`、`RoleChanged`、`MemberLevelUpgraded`
- 载荷：包含业务最小必要字段与 schemaVersion
- 传输：单体阶段可用进程内 EventEmitter/Redis；演进后可切换 NATS/Kafka（接口不变）

示例：
```json
{
  "event": "UserCreated",
  "schemaVersion": 1,
  "occurredAt": "2025-08-25T12:00:00Z",
  "data": {
    "userId": 123,
    "username": "alice",
    "email": "alice@example.com",
    "roles": ["admin"]
  },
  "traceId": "..."
}
```

推荐事件清单（节选）：
- IAM：`UserCreated`、`UserDisabled`、`RoleChanged`、`PasswordReset`
- Member：`MemberRegistered`、`MemberLevelChanged`、`MemberSignedIn`
- Notification：`NotificationSent`、`TemplateUpdated`
- Upload：`FileUploaded`、`FileDeleted`

## 4. 版本与兼容
- OpenAPI 契约版本化（`/v1`、`/v2`）；向后兼容优先，废弃通过 Deprecation 标记与迁移指引
- 事件 schema 版本化（字段新增向后兼容，删除需过渡期）
- SDK 语义化版本（SemVer），扩展声明 `engines.wwjcloud` 兼容范围

## 5. 最小 SDK 结构（站内调用优先）
建议将每个域提供一个可替换实现的 SDK 包（先本地模块，后可独立 npm 包）：

```
packages/
  iam-sdk/
    src/
      index.ts           # Facade：公开接口
      types.ts           # DTO/接口类型
      events.ts          # 事件常量与载荷类型
      impl.inproc.ts     # 站内实现（直调服务）
      impl.http.ts       # 远程实现（HTTP/RPC，可后置）
    package.json

  member-sdk/
    src/...

  settings-sdk/
    src/...
```

使用方式：
```ts
// 业务层仅依赖接口
import { IamService } from '@wwjcloud/iam-sdk';

const ok = await iamService.checkPermission({
  userId: currentUser.id,
  resource: 'order',
  action: 'read',
});
```

切换远程实现：
- 通过依赖注入或配置切换 `impl.inproc` → `impl.http`
- 业务层无感知，仅配置变更

## 6. 配置、网关与观测基线
- 配置：集中管理 + 命名空间（含扩展 `addons.<name>.*`），强校验
- 网关：所有入口统一经过网关（内置或可替换），鉴权与限流前置
- 观测：统一日志/指标/追踪接口，预留 Prometheus/Jaeger 适配

## 7. 拆分准备的验收标准
- 无跨域直查库；接口/事件契约稳定
- 服务无状态（或将状态外部化）；可水平扩展
- SDK 覆盖全部对外调用场景，具备双实现（站内/远程）
- 有基础观测（日志/指标/追踪）与健康检查

---
以上规范将作为“单体 → 微服务”演进的基础约束。后续可在本页扩充各域的 API/事件详规与示例代码。 