docs: consolidate runnable examples and publish v0.1.1 guides
This commit is contained in:
106
examples/README.md
Normal file
106
examples/README.md
Normal file
@@ -0,0 +1,106 @@
|
||||
# Orbit 可运行示例
|
||||
|
||||
这里集中提供 27 个场景：24 个轻量 SDK 程序和 3 个包含业务数据库的完整工程。每个目录的 README 都有用途、前置条件、运行命令、预期结果及详细接口链接。
|
||||
|
||||
## 第一次使用
|
||||
|
||||
1. 按[根 README](../README.md#快速开始)迁移数据库、设置管理员并启动 Orbit。
|
||||
2. 从 `health` 检查服务，再运行 `worker` 看完整提交与执行结果。
|
||||
3. 接入已有业务优先阅读 `http-service`；只需要事务发送器，使用公共 [Outbox 适配包](../adapters/outbox/mysql/README.md)。
|
||||
|
||||
轻量示例在根 `examples/go.mod` 中，仓库 `go.work` 联调本地 SDK；`GOWORK=off` 时使用已发布的最低兼容版本 v0.1.0。v0.1.1 的这些 SDK API 保持不变。三个业务工程各有独立 go.mod，用 `GOWORK=off` 运行；它们保留仓库内开发用的 replace。**业务方自己的项目安装正式 v0.1.1，无需复制这些 replace。**
|
||||
|
||||
从仓库根目录执行：
|
||||
|
||||
```sh
|
||||
export ORBIT_URL=http://127.0.0.1:8080
|
||||
export ORBIT_CREDENTIALS_FILE="$PWD/.local/development.credentials.json"
|
||||
cd examples
|
||||
go run ./health
|
||||
go run ./worker
|
||||
```
|
||||
|
||||
SDK 凭据是程序调用接口的身份，不是业务数据。任务、流程、结果与审计在 MySQL；控制台使用账号密码登录，无需上传凭据文件。
|
||||
|
||||
## 全部示例
|
||||
|
||||
| 目录 | 功能 | 本例实际演示 |
|
||||
| --- | --- | --- |
|
||||
| [health](health/README.md) | 健康检查 | 查询存活、数据库/迁移就绪状态与运行版本。 |
|
||||
| [tasks](tasks/README.md) | 任务提交与幂等 | 同一请求提交两次，查询任务和直接来源，再按版本取消。 |
|
||||
| [worker](worker/README.md) | 自动 Worker | 注册文本处理器，执行三条任务，确认结果后有界排空。 |
|
||||
| [file-conversion](file-conversion/README.md) | CSV 转 JSON | 提交小型 CSV 内容，Worker 转为 JSON，并核对行数和输出。 |
|
||||
| [delayed-task](delayed-task/README.md) | 延迟任务 | 等待 1500 毫秒后执行，核对未提前开始及原受理回执。 |
|
||||
| [batch](batch/README.md) | 批量与部分补交 | 三项受理中两项成功、一项满额；原身份核对并只补交失败项。 |
|
||||
| [retry](retry/README.md) | 有限安全重试 | 第一次明确失败且未产生效果，退避后第二次成功。 |
|
||||
| [cancellation](cancellation/README.md) | 运行中取消 | 处理器收到取消意图后配合停止，确认没有未结清效果。 |
|
||||
| [task-query](task-query/README.md) | 任务筛选与分页 | 按精确业务键和创建时间翻页，核对时间上界与原载荷，再取消收尾。 |
|
||||
| [history](history/README.md) | 执行历史与迟到证据 | 保存成功结果后提交冲突报告，查询尝试及证据，确认原结果没有被覆盖。 |
|
||||
| [recovery](recovery/README.md) | 人工核查与关联重试 | 模拟未知效果，凭证据核查为失败，再创建关联的新任务并成功执行。 |
|
||||
| [schedules](schedules/README.md) | 定时计划 | 创建有限周期计划，恢复运行，读取固定版本触发来源，最后暂停并排空。 |
|
||||
| [resources](resources/README.md) | 队列配额与限速 | 制造队列积压背压，释放额度后以原身份补交，并验证受控执行。 |
|
||||
| [application-resources](application-resources/README.md) | 跨命名空间共享额度 | 同一应用下两个命名空间共享上限，释放后原身份重报，并恢复配置。 |
|
||||
| [keyed-concurrency](keyed-concurrency/README.md) | 跨队列资源互斥 | 两队列操作同一资源键，验证许可序号递增及资源端拒绝旧写。 |
|
||||
| [priority](priority/README.md) | 优先级 | 以单执行槽展示近同时到期的任务按 9、4、0 优先级执行。 |
|
||||
| [subscriptions](subscriptions/README.md) | 结果订阅管理 | 创建订阅、同键核对、暂停、恢复及查询，最后暂停本次订阅。 |
|
||||
| [event-protocol](event-protocol/README.md) | WebSocket 结果通知与 ACK | 接收取消事件并确认，断开后重报原证明，验证 ACK 去重。 |
|
||||
| [worker-protocol](worker-protocol/README.md) | Worker 底层协议 | 手动完成注册、领取、开始授权、结果确认和查询，了解协议边界。 |
|
||||
| [workflow-definition](workflow-definition/README.md) | 流程定义与版本发布 | 研发通过 SDK 定义并发布 v1/v2，核对原版本与结构预算。 |
|
||||
| [workflow](workflow/README.md) | 并行流程、汇合与信号 | 两条并行任务汇合，等待信号后推进，并查询来源和状态时间线。 |
|
||||
| [workflow-query](workflow-query/README.md) | 流程实例筛选与分页 | 创建带业务键的实例，按业务键/状态/时间分页并核对尾部空格精确匹配。 |
|
||||
| [workflow-poll](workflow-poll/README.md) | 有界查询 | 提交外部作业一次，区分处理中轮次与请求失败重试，并演示轮次耗尽。 |
|
||||
| [workflow-recovery](workflow-recovery/README.md) | 流程证据核查与恢复 | 外部受理后丢响应，按证据核查、解决步骤、解除核查并显式恢复暂停。 |
|
||||
| [task-outbox](task-outbox/README.md) | 业务事务 Outbox | 业务记录与待发请求同事务，后台提交及原身份恢复 |
|
||||
| [result-inbox](result-inbox/README.md) | 业务结果 Inbox | 同事务去重和更新业务视图，提交后 ACK |
|
||||
| [http-service](http-service/README.md) | 嵌入 HTTP 服务 | HTTP → Outbox → Worker → 结果 Inbox，完整启动、就绪和关闭 |
|
||||
|
||||
## 权限与准备
|
||||
|
||||
根 README 的快速开始凭据用于专用演示环境，包含 Worker、计划、订阅、任务恢复和全部流程权限。若单独初始化，按各例要求选择：
|
||||
|
||||
| 能力 | bootstrap 参数 |
|
||||
| --- | --- |
|
||||
| Worker 执行 | `--worker-access` |
|
||||
| 定时计划 | `--schedule-access` |
|
||||
| 结果订阅 | `--event-access` |
|
||||
| 独立任务核查/重试 | `--recovery-access` |
|
||||
| 定义发布 | `--workflow-access` |
|
||||
| 实例启动/读取 | `--workflow-run-access` |
|
||||
| 暂停/恢复/取消 | `--workflow-control-access` |
|
||||
| 外部信号 | `--workflow-signal-access` |
|
||||
| 步骤核查/恢复 | `--workflow-recovery-access` |
|
||||
| 流程审计/时间线 | `--workflow-audit-access` |
|
||||
| 应用共享额度 | `--resource-access`，见 application-resources 的双命名空间初始化 |
|
||||
|
||||
已有凭据不会因修改命令自动增加权限。不要重复 bootstrap 覆盖原凭据；需要另一个场景时按对应手册创建独立示例应用并保存新文件。生产凭据按实际角色和队列收紧权限。
|
||||
|
||||
需要完整流程演示凭据时，在已配置 `ORBIT_MYSQL_DSN` 的仓库根目录执行一次：
|
||||
|
||||
```sh
|
||||
umask 077
|
||||
mkdir -p .local
|
||||
go run ./cmd/orbit-admin bootstrap \
|
||||
--application workflow-examples --namespace default --environment development \
|
||||
--queue workflow --worker-access --workflow-access --workflow-run-access \
|
||||
--workflow-control-access --workflow-signal-access --workflow-recovery-access \
|
||||
--workflow-audit-access --output .local/workflow.credentials.json
|
||||
export ORBIT_CREDENTIALS_FILE="$PWD/.local/workflow.credentials.json"
|
||||
cd examples
|
||||
go run ./workflow
|
||||
go run ./workflow-poll
|
||||
go run ./workflow-recovery
|
||||
```
|
||||
|
||||
三个业务数据库工程的 `init` 仅用于新建专用空库；连接配置、命令参数与 API 请求分别在各自 README 链接的运行手册中。其数据库不能用 Orbit 平台库替代。
|
||||
|
||||
## 执行与恢复约定
|
||||
|
||||
- `ACCEPTED` 是任务已被平台受理；执行成功以查询或结果事件为准。
|
||||
- 短示例通常随机创建身份用于独立演示；重启短示例不是恢复旧业务，持久恢复参考 Outbox/Inbox 工程。
|
||||
- `PENDING` 查询结果表示继续等待，网络失败重试属于另一层预算。
|
||||
- 示例使用真实接口并保留审计，不清空平台数据库。订阅、定义和队列会累计，应在专用环境演练。
|
||||
- 外部系统有未知效果时应核查；处理器自己的幂等、事务和证据不能由重连机制替代。
|
||||
|
||||
## 回归
|
||||
|
||||
从仓库根目录执行 `make test vet build` 覆盖全部示例模块；`make integration` 使用临时 MySQL 和真实 Orbit 进程运行场景与故障测试。仅跑 `go test ./...` 而未提供集成环境时，外部服务用例会跳过。
|
||||
Reference in New Issue
Block a user