57 lines
4.5 KiB
Markdown
57 lines
4.5 KiB
Markdown
# 标准能力与依赖
|
||
|
||
内置 package 不需要 import、下载或把标准库复制到 module/。先查已有能力，避免项目里堆积 parse_id、page_slice、trim 包装函数。
|
||
|
||
| 能力 | 入口 |
|
||
| --- | --- |
|
||
| 文本 | `text.trim/lower/upper/contains/starts_with/ends_with/split/replace/join` |
|
||
| 数字 | `int.parse/to_text`、`decimal.parse/round/from_int`、`float.parse`、`math` |
|
||
| 字节 | `dever.bytes.from_text/to_text/from_ints/length/at/slice/concat` |
|
||
| 时间 | `dever.time.now/parse_datetime/format_datetime/parse_date/format_date/duration/add/subtract/difference` |
|
||
| 密码与摘要 | `dever.crypto.password_hash/password_verify/token/sha256/hmac_sha256/constant_time_eq` |
|
||
| 类型化 JSON | `dever.json`，API/CMD 自动按声明类型解析和输出 JSON |
|
||
| HTTP/网络/文件 | `dever.http`、`dever.net`、`dever.io`，业务外部 I/O 按 Port 边界使用 |
|
||
| 请求与身份 | `dever.api`、`dever.auth`、`dever.site`；只有允许的入口调用链能使用 |
|
||
|
||
参数、返回值和错误见 [签名索引](signatures.md)，无需下载源码。索引未覆盖的能力再查官方同版本 `library/`。解析失败可能返回 null，也可能产生声明的错误，不能一律当成 0。发布新版本时要核对索引与实际库声明。
|
||
|
||
## Dever Package
|
||
|
||
Package 是可复用 Dever 组件。通过项目 setting.json 中的 `package.registry` 与 `package.use` 声明；显式 `dever package add|list|update|remove|doctor <root> ...` 管理。`dever.lock` 固定版本、摘要和传递依赖；Package 不能覆盖本地同名组件。不要在业务源码中引入 import 或自建 vendor 查找规则。
|
||
|
||
## 外部 Lib 与普通二进制
|
||
|
||
第三方生态叫 Lib，在 `config/setting.json` 的根 lib 数组声明。Python 用 `pip:name@version`，JS 用 `npm:name@version`，Go 用对应模块路径和版本。
|
||
|
||
用 `dever lib add/list/install/update/remove/doctor` 管理依赖。add/update 准备所需运行环境与构建工具；install 按已有锁恢复，不改配置或锁。run/build 使用锁定结果，不联网，不借用系统 Python、Node、Go 或 PATH。
|
||
|
||
锁记录包的来源、摘要、构建输入与产物。新机器缺少构建结果时，install 按记录重建并核对摘要。重建结果不一致就失败，不能偷偷换版本或改锁；需要重新选版本时，由用户决定执行 update。
|
||
|
||
Lib 必须通过领域 Port/Adapter 使用：Port 声明参数、结果和业务错误，Adapter 提供实现，App 只调用 Port。各种语言共用 Worker 协议，统一检查类型、错误、超时和授权能力。SDK 和运行环境必须匹配 Dever 版本，SDK 不能代替编译器类型检查。
|
||
|
||
完整 Port、每例独立的 fake、三种语言实现和配置见 [外部 Lib 示例](external-lib.md)。按示例导出同名处理函数，不手写 schema hash、协议握手或操作注册表。
|
||
|
||
Dever 不检查第三方语言源码内部的函数拆分、重复实现和业务硬编码；Port 类型与 Worker 协议验证不能代替这部分审查。外部生态承接确需复用的现成能力，不能用于转移普通业务逻辑以规避 Dever 约束，开发规则仍见 [项目开发](development.md)。
|
||
|
||
普通 Linux 二进制不需要 Worker 协议。领域 `port.dever`：
|
||
|
||
源码：[二进制 Port](../assets/examples/command/module/document/tool/port.dever)
|
||
|
||
```dever
|
||
execute(args: List<Text>, stdin: Bytes?) (output: dever.process.Output) fails dever.process.Error
|
||
```
|
||
|
||
`adapter.dever`：
|
||
|
||
源码：[二进制 Adapter](../assets/examples/command/module/document/tool/adapter.dever)
|
||
|
||
```dever
|
||
external command "bin/tool" {}
|
||
```
|
||
|
||
将相应架构 ELF 放在领域的 bin/tool，App 调用 `port.execute(["--version"], null)`。结果有 code、stdout、stderr，字节显式转文本；参数不是 shell 字符串。非零退出码仍是结果，启动失败/超时/超限是错误。文件、网络、子进程能力仍显式声明，但不构成 OS 沙箱；执行权限继承容器用户。不要把可信 Worker 当作不可信代码隔离环境。
|
||
|
||
测试必须使用 Port fake，不执行真实第三方程序。跨到 ARM 时必须提供目标架构的库和二进制，Dever 不转换已有 x86 ELF。
|
||
|
||
[command 项目](../assets/examples/command/) 包含 App、CMD、配置和 fake 测试，可直接 check/test。App 将 stdout/stderr 转成 Text，保留退出码后输出 JSON。本示例不附带 bin/tool；真实 run/build 前必须放入自己需要的目标架构 ELF 和依赖，不能把 fake 结果当成真实程序输出。
|