nats-design-subject

设计 NATS 主题层级

设计一种主题架构，让订阅者能够使用通配符高效导航，同时采用恰当的分段顺序、支持基于账户的租户隔离，并具备扩展路径。

访谈阶段

仅当以下各项都已明确时，才跳过访谈：

• 消息模式（发布/订阅、请求/响应、流式传输）
• 多租户需求（单租户/多租户、规模要求）
• 安全要求（授权、租户隔离）
• 持久化需求（JetStream 或 core NATS）

以下情况必须进行访谈：迁移现有主题（需要先审查反模式）

问题

1. 范围 — “这是全新设计，还是要迁移现有主题？”

   • 影响：迁移需要先审查反模式（参见 references/anti-patterns.md）

2. 多租户与规模 — “您需要哪种方案：(A) 单租户，(B) 每个租户使用独立账户进行隔离，(C) 使用共享账户并添加主题前缀，(D) 涉及区域/分片的大规模部署？”

   • 影响：决定租户身份应放在 NATS 账户边界内、主题中，还是两者兼有

3. 消息模式 — “您使用哪些模式？(A) 仅发布/订阅，(B) 请求/响应，(C) 流式传输/JetStream，(D) 全部/混合？”

   • 影响：JetStream 需要考虑流的主题设计；请求/响应有其自身约定

4. 安全 — “您需要账户级隔离、基于主题的授权，还是两者都需要？”

   • 影响：决定账户边界、导出/导入、租户前缀和权限边界

5. 持久化 — “您需要 JetStream 持久化，还是仅使用 core NATS？”

   • 影响：决定流/消费者主题设计及保留策略

---

适用场景

• 设计新的 NATS 消息系统
• 规划基于账户的多租户主题隔离
• 组织设备遥测数据或事件流
• 在微服务之间设置请求/响应模式
• 为事件溯源系统定义事件主题结构
• 构建具有 Agent 间消息传递功能的 Agentic AI 平台

不适用场景

• 配置 NATS 服务端或集群设置（属于基础设施配置，而非主题设计）
• 编写 NATS 客户端代码或连接逻辑（属于实现，而非架构）
• 在 NATS 和其他消息系统之间做选择（属于技术评估）
• 排查现有 NATS 连接或性能问题

---

工作流

1. 确定领域边界

列出所有涉及的 NATS 账户边界和业务领域。对于严格的多租户场景，优先为每个租户使用一个账户；然后在每个账户内设计简短、领域优先的主题。

仅当无法使用账户，或设计的共享/平台接口必须携带租户来源信息时，才使用主题租户前缀。

2. 选择模式

将用户场景与相应模式匹配：

用例	模式	示例
简单领域	{domain}.{action}.{scope}	orders.created.us-west
多区域	{domain}.{action}.{region}.{id}	devices.telemetry.us-east.sensor-456
多租户 SaaS	每个租户使用独立账户，主题：{domain}.{action}.{id}	账户 acme-corp 中的 analytics.processed.report-123
共享账户回退方案	{tenant}.{domain}.{action}.{id}	acme-corp.analytics.processed.report-123
多租户 AI	每个租户使用独立账户，主题：agents.{action}.{agent-id}.{task-id}	账户 tenant-abc 中的 agents.task-assigned.agent-xyz.task-123
请求/响应	{service}.request / {service}.reply	orders.request / orders.reply
事件溯源	{aggregate}.{action}.v{version}.{id}	orders.order.created.v1.order-123

如需了解完整的模式详情，包括订阅者路径和扩展指南，请阅读 references/patterns.md。

3. 合理规划片段顺序

在所选账户内按从左到右的顺序排列主题片段时，请遵循以下规则：

• 从宽泛到具体：域 → 操作 → 范围 → 标识符
• 低基数在左，高基数在右：先放区域（值较少），再放 ID（值有数百万个）
• 绝不把 ID 或 UUID 放在操作之前

✓ GOOD: orders.created.us-west.order-123
                            ↑          ↑
                       low-card    high-card

✗ BAD:  orders.order-123.us-west.created
                ↑
           high-card early (kills wildcard filtering)

为什么这很重要：NATS 通配符匹配会从左到右扫描。高基数值放在左侧，会迫使订阅者使用低效的 orders.*.us-west.created 模式，而该模式必须匹配数千个 ID。

有关常见的顺序错误和迁移策略，请阅读 references/anti-patterns.md。

4. 规划订阅者路径

针对每个域，记录订阅者将如何筛选：

orders.>                    → All order events
orders.created.>            → All order creation events
orders.created.us-west.>    → Orders created in US West
orders.created.us-west.order-123 → Specific order

围绕订阅者而非发布者设计主题。订阅者决定如何组织主题——良好的层级结构能让他们通过通配符高效筛选。

5. 设计安全模型（如使用多租户）

如果用户需要租户隔离或基于角色的访问：

• 优先使用 NATS 账户实现租户隔离；每个租户都有自己的主题命名空间
• 使用导出/导入实现跨账户联合，而不要假设租户之间可以互相查看
• 仅在使用共享账户作为后备方案或在平台聚合层使用主题中的租户 ID
• 将管理/平台主题与用户操作分开（_admin.> 或平台账户主题）
• 为每项服务应用最小权限原则

有关基于账户的多租户、授权模式和租户隔离示例，请阅读 references/security.md。

6. 设计 JetStream 流（如需持久化）

如果用户需要 JetStream：

• 将 JetStream 流、消费者和 KV 存储桶视为账户范围的资源
• 当拓扑结构相同时，在各租户账户中重复使用流/KV 名称
• 在每个租户账户内按域创建一个流
• 仅在一个共享账户中使用按租户划分的流作为后备方案
• 使用消费者筛选器实现精细路由
• 设置账户和域的保留期限限制（财务数据：数年；遥测数据：数天）
• 最多使用 4-6 个主题片段——使用消费者筛选器，而不是更深的层级结构

有关流设计、消费者模式以及从核心 NATS 迁移的内容，请阅读 references/jetstream.md。

7. 验证并编写输出

使用以下模板呈现设计：

# NATS Subject Architecture: [System Name]

## Domain Overview
[Describe the domains and their interactions]

## Subject Hierarchy

### Domain: [Name]
- `domain.action.{scope}.{id}`
- `domain.action.{scope}.{id}`

Subscriber paths:
- `domain.>` — All events
- `domain.action.>` — Specific action

[Repeat for each domain]

## Multi-Tenancy Model
[NATS Accounts, exports/imports, or shared-account subject prefixes]

## Security Model
[Authorization rules per role/service, if applicable]

## JetStream Streams
[Account-scoped stream definitions and consumer filters, if applicable]

## Quality Validation
[Run checklist below]

输出示例

# NATS Subject Architecture: IoT Smart Building Platform

## Domain Overview

Smart building system with 10,000+ sensors across multiple regions sending temperature, humidity, and occupancy data. Needs real-time monitoring, regional aggregation, and alerting.

## Subject Hierarchy

### Domain: Devices
- `devices.telemetry.{region}.{device-id}.{metric}`
- `devices.telemetry.us-west.sensor-456.temperature`
- `devices.telemetry.us-west.sensor-456.humidity`
- `devices.telemetry.eu-central.sensor-789.occupancy`

Subscriber paths:
- `devices.telemetry.>` — All telemetry (global monitoring)
- `devices.telemetry.us-west.>` — Regional dashboard (US West)
- `devices.telemetry.>.>.temperature` — All temperature readings

### Domain: Alerts
- `alerts.triggered.{severity}.{region}.{device-id}`
- `alerts.triggered.critical.us-west.sensor-456`

Subscriber paths:
- `alerts.triggered.critical.>` — Critical alerts only
- `alerts.triggered.>.us-west.>` — Regional alert dashboard

## Multi-Tenancy Model

Not applicable (single organization)

## Security Model

- Building operators: `devices.telemetry.>`, `alerts.>` (subscribe only)
- Alert service: `alerts.>` (publish + subscribe)
- Admin: `>` (full access)

## JetStream Streams

Stream: `telemetry-us-west`
  Subjects: `devices.telemetry.us-west.>`
  Retention: 24h (high volume)
  
Stream: `alerts`
  Subjects: `alerts.>`
  Retention: 30d

## Quality Validation

✓ All segments follow broad-to-specific order
✓ Device IDs at rightmost position
✓ Naming consistent (lowercase, hyphens)
✓ Regional filtering efficient
✓ 4 segments (within 4-6 limit)

有关微服务、IoT、SaaS、事件溯源和 Agentic AI 平台的完整真实案例，请阅读 references/use-cases.md。

---

快速开始（简单场景）

如果你正在为没有多租户需求的简单单域系统进行设计：

1. 使用模式 1（简单域）：{domain}.{action}.{id}
2. 跳过参考文档——遵循上述工作流
3. 示例：orders.created.order-123、payments.authorized.payment-456

对于多区域、多租户或事件溯源需求，请继续执行完整工作流，并按需阅读参考文档。

---

参考文档导航

此技能包含 5 份详细的参考文档——在工作流的相应步骤中按需阅读：

• patterns.md：选择初始模式时阅读（第 2 步）
• anti-patterns.md：迁移或审查现有主题时阅读
• security.md：需要多租户/授权时阅读（第 5 步）
• jetstream.md：需要持久化时阅读（第 6 步）
• use-cases.md：阅读各个域的完整实例

不要一开始就阅读所有参考文档——根据工作流需要逐步查阅。

---

命名规则

• 全部使用小写字母，并以连字符分隔：orders.created ✓
• 不要使用下划线：orders_created ✗
• 不要混用大小写：Orders.Created ✗
• 最多使用 4-6 个片段

---

质量检查清单

• 所有主题段都遵循由宽到窄的顺序（{domain}.{action}.{scope}.{id}）
• UUID/ID 字段不会出现在操作/范围段之前
• 命名保持一致（全部小写，使用连字符，不使用下划线）
• 为每个域记录订阅者通配符路径
• 主题段不超过 6 段
• 多租户边界清晰（每个租户使用独立账户、共享账户前缀回退，或两者兼用）
• 定义用于管理/监控访问的安全主题
• 不存在冲突模式（例如，orders.created.123 与 orders.123.created）
• 记录高基数决策（说明为何选择该 ID 位置）

测试你的设计

部署前验证主题层级：

# Start local NATS server
nats-server -D

# Test subscriber wildcards
nats sub "orders.>"                    # Should match all order subjects
nats sub "orders.created.>"            # Should match only creations
nats sub "orders.created.us-west.>"    # Should match region-specific

# Test publishing
nats pub "orders.created.us-west.order-123" "test message"

# Verify JetStream streams (if applicable)
nats stream info orders-stream
nats consumer info orders-stream order-consumer

对于现有部署，审计当前主题：

# List active subjects (requires monitoring enabled)
nats server report jetstream

# Check subject permissions
nats server check connection --account <account-name>

参考文档

• 模式：6 种层级模式，包含订阅者路径和扩展指南
• 反模式：常见错误及其检测方法、修复方案和迁移策略
• 安全与多租户：授权模式和租户隔离
• JetStream 设计：流过滤器、消费者主题和保留策略
• 用例：微服务、IoT、SaaS、事件溯源和 Agentic AI 的完整示例