用途:设计 ObjectStack 运行时对外暴露的服务端 API 面,包括 REST 端点、认证提供方、实时通道、错误信封与批量契约。
主要能力:
- 自动生成 API:对象设 apiEnabled: true(默认)即获得 /api/v1/data/{object} 的列表、单条读写、删除、query(QueryAST 聚合)与 batch 端点;跨对象原子批量为 POST /api/v1/batch。若对象定义 apiMethods,仅暴露其中操作,[] 表示全部拒绝。
- 元数据 API:/api/v1/meta/:type 与 /api/v1/meta/:type/:name 读取元数据。
- 匿名表单端点:FormView 需 sharing 同时声明 enabled: true、allowAnonymous: true 与 publicLink slug,否则 404 FORM_NOT_FOUND;挂载于 GET /api/v1/forms/:slug 与 POST /api/v1/forms/:slug/submit,绕过 enforceAuth,以 guest_portal 合成上下文运行,仅保留表单字段白名单。
- 声明式端点:defineStack({ apis }) 以元数据声明 HTTP 端点,路径必须为 /api/v1/apps/<manifest.namespace>/<subpath>,类型支持 object_operation 与 flow;authRequired 默认 true,显式 false 必须配合 rateLimit.enabled: true。inputMapping/outputMapping 仅做点路径字段搬移与重命名,不支持 transform。
- 代码路由:通过 http.server 服务挂载,需在 kernel:ready 钩子中解析服务,规范名 http.server 优先于别名 http-server。
- 认证:AuthProvider 支持 local、google、github、microsoft、ldap、saml;RBAC 与 RLS 属 objectstack-data。
- 错误信封:error.code 为封闭标准目录加各包注册码的并集,未注册码会导致解析与 CI 失败;调度器错误码含 ROUTE_NOT_FOUND、METHOD_NOT_ALLOWED、NOT_IMPLEMENTED、SERVICE_UNAVAILABLE。
- 实时订阅:契约见 spec 的 realtime.zod.ts 与 websocket.zod.ts,支持 websocket、sse、polling。
使用方式:优先使用自动生成 API;仅对 CRUD 加触发器无法表达的业务逻辑创建自定义端点。命名用复数名词、snake_case、动作才用动词、统一 /api/v1/ 前缀。完成后运行 os validate 或 os build 校验。
限制:无 /bulk 与 GET aggregate 路由;DELETE 为硬删除,无回收站;无 upsert 路由,需查询外部唯一 ID 后经 batch 分支写入;PATCH 乐观并发用 If-Match 或 expectedVersion,冲突返回 409 CONCURRENT_UPDATE;数据路由返回扁平 { error, code } 而非统一信封。升级 17 前需按协议升级指南做安全审查。