功能特性
核心特性
简单直观
from onestep import IntervalSource, OneStepApp
app = OneStepApp("demo")
@app.task(source=IntervalSource.every(seconds=30))
async def my_task(ctx, item):
print("处理:", item)多种数据源
| 类型 | Source | Sink | 描述 |
|---|---|---|---|
| 内存队列 | 支持 | 支持 | 开发测试 |
| 定时器 | 支持 | 不支持 | Cron/Interval |
| Webhook | 支持 | 不支持 | HTTP 接收 |
| HTTP Sink | 不支持 | 支持 | HTTP JSON 输出 |
| RabbitMQ | 支持 | 支持 | 分布式队列 |
| Redis Streams | 支持 | 支持 | 轻量级流队列 |
| AWS SQS | 支持 | 支持 | 云队列 |
| Cloudflare Queues | 支持 | 支持 | HTTP 拉取消费者队列 |
| MySQL | 支持 | 支持 | 表队列/增量同步/binlog CDC/表输出/跟踪长任务执行 |
| PostgreSQL | 支持 | 支持 | 表队列/增量同步/表输出/跟踪长任务执行 |
| Kafka | 支持 | 支持 | topic 消费与生产 |
| MongoDB | 支持 | 支持 | Collection 轮询/Change Stream/表输出 |
| Elasticsearch / OpenSearch | 不支持 | 支持 | 异步 bulk Sink |
| ClickHouse | 不支持 | 支持 | 异步确认表输出 Sink |
| Feishu Bitable | 支持 | 支持 | 多维表格增量同步/表输出 |
| 自定义 | 支持 | 支持 | 任意数据源 |
灵活流转
from onestep import CronSource
from onestep_sql.mysql import MySQLConnector
from onestep_rabbitmq import RabbitMQConnector
rmq = RabbitMQConnector("amqp://...")
db = MySQLConnector("mysql+pymysql://...")
results = rmq.queue("results")
@app.task(source=CronSource("0 * * * *"), emit=results)
async def scheduled_to_mq(ctx, _):
return {"data": "..."}
@app.task(source=results, emit=db.table_sink(table="results"))
async def mq_to_db(ctx, item):
return item并发控制
@app.task(source=..., concurrency=4)
async def task1(ctx, item):
...
@app.task(source=..., concurrency=64)
async def task2(ctx, item):
...重试机制
from onestep import MaxAttempts
@app.task(
source=...,
retry=MaxAttempts(max_attempts=3, delay_s=1.0),
)
async def might_fail(ctx, item):
...max_attempts 包含首次执行。上面的配置表示首次执行失败后最多再尝试 2 次。
死信队列
@app.task(
source=main_queue,
dead_letter=dead_letter_queue,
retry=MaxAttempts(max_attempts=3),
)
async def risky_task(ctx, item):
...
@app.task(source=dead_letter_queue)
async def handle_dead_letter(ctx, item):
print(item["payload"])
print(item["failure"])执行超时
@app.task(source=..., timeout_s=30.0)
async def long_task(ctx, item):
await asyncio.sleep(60)超过 timeout_s 后,运行时会取消任务并按失败流程处理。
事件监听
from onestep import InMemoryMetrics, OneStepApp, StructuredEventLogger, TaskEventKind
app = OneStepApp("demo")
metrics = InMemoryMetrics()
app.on_event(metrics)
app.on_event(StructuredEventLogger())
@app.on_event
def log_success(event):
if event.kind is TaskEventKind.SUCCEEDED:
print(f"成功:{event.task}")状态管理
from onestep import InMemoryStateStore, OneStepApp
app = OneStepApp("demo", state=InMemoryStateStore())
@app.task(source=...)
async def track_runs(ctx, item):
runs = await ctx.state.get("runs", 0)
await ctx.state.set("runs", runs + 1)
print(f"第 {runs + 1} 次运行")生命周期钩子
@app.on_startup
async def bootstrap(app):
print("应用启动")
@app.on_shutdown
async def cleanup(app):
print("应用关闭")YAML 配置
app:
name: my-app
resources:
rmq:
type: rabbitmq
url: amqp://guest:guest@localhost/
timer:
type: interval
minutes: 5
queue:
type: rabbitmq_queue
connector: rmq
queue: jobs
notify:
type: http_sink
url: "https://example.com/hooks/jobs"
tasks:
- name: process_jobs
source: timer
emit: [queue, notify]
handler:
ref: myapp.tasks:process_jobs
retry:
type: max_attempts
max_attempts: 3Worker 打包
onestep check --strict worker.yaml
onestep build worker.yaml --strict --out dist/worker.ziponestep build 会收集 YAML 入口、Python handler/hook/条件路由引用、依赖声明文件和 README/license 等元数据,生成带 onestep-package.json manifest 的可部署 zip。
AI 与自动化接口
onestep check --strict --json worker.yaml # 一次报告全部校验问题
onestep schema # 输出 onestep/v1alpha1 JSON SchemaCLI 输出是给程序消费的稳定契约:退出码(0 成功 / 1 运行失败 / 2 输入无效)、带 schema/version 的 --json 输出(失败时也输出错误信封)、以及从运行时严格校验契约与已安装连接器目录派生的 JSON Schema,可供编辑器补全或 AI 自校验生成的配置。详见 AI 与自动化接口。
高级特性
多语言客户端与按需拉取
- 长程任务的
ExecutionClient除 Python 外还有官方 TypeScript 实现@mic1on/onestep-client(npm,PostgreSQL 后端):Next.js API route 或任意 Node ≥ 22.6 服务可以直接提交、轮询、取消长任务,worker 保持未改动的 Python onestep;包内逐字节复刻 Python 的提交摘要与 JSON 编码规则,避免跨语言幂等键漂移。详见长程任务如何工作。 HttpFetcher(1.13.0 起)是声明式的按需 HTTP 拉取资源:运行时不轮询它,handler 在执行中通过ctx.resources调用fetch()/fetch_rows(),复用http_sink的传输栈与错误分类,失败交给任务 retry policy。详见 HTTP Sink / Fetcher。
任务编排
from onestep import MemoryQueue
input_queue = MemoryQueue("input")
stage1_out = MemoryQueue("stage1")
stage2_out = MemoryQueue("stage2")
@app.task(source=input_queue, emit=stage1_out)
async def stage1(ctx, item):
return item * 2
@app.task(source=stage1_out, emit=stage2_out)
async def stage2(ctx, item):
return item + 1
@app.task(source=stage2_out)
async def final(ctx, item):
print(f"结果:{item}")链式拓扑可以用 onestep render your_package.tasks:app 输出为 Mermaid 图快速确认接线是否正确,详见 生产部署。
优雅关闭
app = OneStepApp("demo", shutdown_timeout_s=30.0)
@app.task(source=...)
async def task(ctx, item):
await process(item)
@app.task(source=...)
async def shutdown_trigger(ctx, item):
ctx.app.request_shutdown()配置管理
app = OneStepApp(
"my-app",
config={
"region": "cn",
"debug": True,
"batch_size": 100,
},
)
@app.task(source=...)
async def task(ctx, item):
region = ctx.config["region"]
debug = ctx.config.get("debug", False)Control Plane 集成
先安装 control-plane reporter 插件:
pip install 'onestep[control-plane]'from onestep import ControlPlaneReporter, ControlPlaneReporterConfig
app = OneStepApp("my-app")
reporter = ControlPlaneReporter(
ControlPlaneReporterConfig.from_env(
app_name=app.name,
service_description="同步计费数据到数仓",
)
)
reporter.attach(app)也可以继续使用 reporter: true,再通过 ONESTEP_SERVICE_DESCRIPTION 注入服务级描述。 Reporter 会推送拓扑同步、心跳、指标和事件,也可以接收 pause_task、resume_task、restart_task 等远程任务控制命令。任务处理函数可以通过 ctx.metrics.counter(...).inc() 和 ctx.metrics.gauge(...).set() 上报低基数自定义指标。
从 onestep-control-plane 0.2.0 起,Reporter 还会在主循环心跳迟到时补发独立心跳(presence beacon),避免 handler 同步阻塞事件循环时实例被控制面误判为离线并反复上下线。该线程在循环健康时不发任何请求,因此现有部署行为不变;卡顿期间实例保持"在线",但阻塞仍会影响任务吞吐与 ping/drain 等命令响应,建议同步阻塞逻辑改用 asyncio.to_thread()。可用 ONESTEP_CONTROL_PLANE_PRESENCE_ENABLED 关闭,用 _INTERVAL_S / _GRACE_S 调整节奏。
对比 0.5.x
| 特性 | 0.5.x | 1.x |
|---|---|---|
| 装饰器 | @step | @app.task |
| 消息来源 | from_broker | source |
| 消息输出 | to_broker | emit |
| 并发控制 | workers | concurrency |
| 启动方式 | step.start() | app.run() / CLI |
| 重试策略 | TimesRetry 等 | MaxAttempts |
| 中间件 | BaseMiddleware | 事件钩子 |
| 状态 | 无 | ctx.state |
| 配置 | 无 | ctx.config |
| 生命周期 | 有限 | @app.on_startup/shutdown |