5.2 KiB
Python、JavaScript 与 Go SDK
SDK 用于把现成的 Python、JavaScript 或 Go 能力接入 Dever。应用先声明 Port，再用外部 Adapter 对接；Dever 会管理 Worker 进程和通信。
开发应用先看 三种语言的完整例子。那里包含同一 Port、三种 Adapter、处理函数和 fake 测试，不需要手写协议或维护另一份接口注册表。
处理函数怎么写
函数名与 Port 操作名对应。输入、输出和业务错误的类型由 Dever 编译器生成，SDK 负责验证。
| 语言 | 处理函数 | 加载生成的接口定义 |
|---|---|---|
| Python | 异步函数 | Worker.from_manifest(manifest, handlers) |
| JavaScript | 函数接收 AbortSignal；支持 ESM 导出或 CommonJS 属性 |
Worker.fromManifest(manifest, handlers) |
| Go | 函数接收 context.Context |
NewFromManifest(manifest)，再 RegisterHandlers(handlers) |
处理函数返回能用 JSON 表达的值，业务失败返回已声明的 BusinessError。不要往 stdout 写日志；stdout 用于 Worker 通信，日志写 stderr。
取消请求会产生一次 dever.cancelled 错误，已取消调用的结果会被丢弃。如果处理函数一秒内不响应取消，Worker 失败并停止接收新调用。Dever 管理进程与 stdin；自行在 Go 进程内调用 Serve 时，调用方负责关闭或解除自己的 io.Reader 阻塞。
SDK 维护与验证
维护 SDK 时，显式指定本机运行环境的绝对路径：
/usr/bin/python3 -B test/external-sdk/check.py --python /usr/bin/python3 --node /absolute/path/to/node --go /absolute/path/to/go
未指定的语言报告 unavailable，不会通过 PATH 猜测。Go 夹具在临时离线缓存中构建。这项检查验证本机 SDK 和类型协议；不能代替发行包或“机器未安装 Python/Node/Go”的运行验收。普通应用测试使用 Port fake，不启动真实 Worker。
编译器通过 ExternalWorkerContract::sdk_manifest() 生成唯一接口定义，包括身份、配置、输入、输出和业务错误。SDK 在 hello 时核对身份，不接受 supervisor 临时指定的 schema。配置在 ready 前解码，只读取 hello.setting。
本目录的三个 example 展示底层 Contract/Worker 注册 API，用于协议夹具。fixture-schema-v1 和 test/external-sdk/typed_contract.json 都是测试数据，不能复制成生产 Port hash。通信帧由 4 字节大端长度和 UTF-8 JSON 组成。
SDK 不依赖第三方包，也不读取环境变量或 PATH。托管 Worker 只读取已打包的 manifest。Python 固定使用 -I -S -B，先加载打包的 SDK，再把 Adapter 与依赖加入 sys.path。
依赖与跨平台构建
dever lib install <project> 按现有锁恢复依赖，不重新选版本、不修改配置或锁。dever-lock-v6 记录 Python extras/wheel METADATA、npm 嵌套依赖及 peers/optional/bundled 依赖、Go 模块校验证据。原始包保留来源与文件名，构建记录保留完整输入，包括 npm 剪除可选构建依赖前的依赖图。
丢失的构建结果由同一沙箱重建，必须与记录的摘要一致。Python 原生 wheel 安装到配套解释器中，必须满足签名声明的标签、扩展 ABI 和动态库依赖要求。
生成 ARM64 应用时，先运行 dever lib update <project> --target linux-aarch64，再运行 dever build <project> --target linux-aarch64 --output <new-file>。Port 和 Worker 源码无需改写；锁、解释器、原生依赖和沙箱资源必须匹配目标平台。缺少目标资源时失败，不借用宿主运行环境。run/test 仍在本机执行。
Go pack 的 build.host 描述编译器、链接器与分析器的运行平台；build.goos/goarch 和标准库对象头描述输出平台。工具在清空的环境中执行，目标必须预先正确配置。
第三方源码构建限制
只有显式准备 Lib 时才构建 Python sdist 或运行 npm 安装钩子。构建使用签名工具包和 Linux 沙箱，输入只读、网络关闭，写入仅限本次临时目录。缺少工具时不回退宿主 PATH。
Python PEP 517 的构建依赖单独锁定，每个 hook 使用新进程，最终 wheel 按保留的元数据核对。npm 的配套运行器处理 preinstall/install/postinstall、依赖 bin 和 node-gyp。
构建记录绑定源码、目标运行环境、工具、构建前端、依赖图和输出摘要。Worker 准备阶段离线恢复结果，不重跑安装钩子。npm .node 产物须通过目标检查、动态加载检查和独立 Node 加载探测，才能进入只读 Worker 目录；线程和子进程也受此限制。不匹配平台或 ABI 的其他变体保留在锁定原始包中，不加入运行目录。运行时原生依赖只能来自 Worker 目录或签名 OS 库，不能借用编译器 sysroot。
生成的原生 addon 验证失败，整个构建就失败；使用纯 JS 备用路径不能证明原生构建成功。当前限制：
- 构建进程最多 5 分钟，stdout/stderr 各最多 16 MiB。
- 每 250 毫秒检查临时目录，限制 512 MiB、65,536 个条目；这是定期检查，检查间隔内可能短暂超出。
- 最终 Worker 最多 256 MiB、65,536 个条目。失败时清理本次拥有的进程。