103 lines
6.8 KiB
Markdown
103 lines
6.8 KiB
Markdown
# 常用标准库真实签名
|
||
|
||
下列签名随 skill 版本维护，参数按位置传入；括号里的输出名也是类型化多输出/Worker/wire 合同的一部分。这里只列常用子集，不复制完整语言手册。每段 `signatures` 对应同名官方 library 包，维护者用根 `test/skill_examples.py` 核对公开声明。
|
||
|
||
## 文本与数字
|
||
|
||
```signatures
|
||
text.trim(value: Text) (result: Text)
|
||
text.lower(value: Text) (result: Text)
|
||
text.upper(value: Text) (result: Text)
|
||
text.at(value: Text, index: Int) (result: Text?)
|
||
text.slice(value: Text, start: Int, end: Int) (result: Text?)
|
||
text.contains(value: Text, pattern: Text) (result: Bool)
|
||
text.starts_with(value: Text, prefix: Text) (result: Bool)
|
||
text.ends_with(value: Text, suffix: Text) (result: Bool)
|
||
text.split(value: Text, separator: Text) (result: List<Text>)
|
||
text.replace(value: Text, pattern: Text, replacement: Text) (result: Text)
|
||
text.join(values: List<Text>, separator: Text) (result: Text)
|
||
int.parse(value: Text) (result: Int?)
|
||
int.to_text(value: Int) (result: Text)
|
||
decimal.parse(value: Text) (result: Decimal?)
|
||
decimal.round(value: Decimal, places: Int) (result: Decimal)
|
||
decimal.from_int(value: Int) (result: Decimal)
|
||
decimal.to_text(value: Decimal) (result: Text)
|
||
float.parse(value: Text) (result: Float?)
|
||
float.from_int(value: Int) (result: Float)
|
||
uuid.parse(value: Text) (result: Uuid?)
|
||
uuid.to_text(value: Uuid) (result: Text)
|
||
dever.id.from_text(text: Text) (id: Id)
|
||
dever.id.to_text(id: Id) (text: Text)
|
||
```
|
||
|
||
Int/Decimal/Float/Uuid parse 失败返回 null，必须用互斥分句处理；不要假定解析失败是 0，也不要把 Uuid、Id 和各 Model 的名义 id 混用。Text 索引按 Unicode 标量值；slice 为起点含、终点不含。
|
||
|
||
## Bytes、时间与密码
|
||
|
||
```signatures
|
||
dever.bytes.from_text(text: Text) (bytes: Bytes)
|
||
dever.bytes.to_text(bytes: Bytes) (text: Text)
|
||
dever.bytes.from_ints(values: List<Int>) (bytes: Bytes)
|
||
dever.bytes.length(bytes: Bytes) (length: Int)
|
||
dever.bytes.at(bytes: Bytes, index: Int) (value: Int?)
|
||
dever.bytes.slice(bytes: Bytes, start: Int, end: Int) (result: Bytes)
|
||
dever.bytes.concat(left: Bytes, right: Bytes) (bytes: Bytes)
|
||
dever.time.now() (output: DateTime)
|
||
dever.time.parse_datetime(text: Text) (output: DateTime) pure
|
||
dever.time.format_datetime(value: DateTime) (output: Text) pure
|
||
dever.time.parse_date(text: Text) (output: Date) pure
|
||
dever.time.format_date(value: Date) (output: Text) pure
|
||
dever.time.duration(millis: Int) (output: Duration) pure
|
||
dever.time.add(value: DateTime, duration: Duration) (output: DateTime) pure
|
||
dever.time.subtract(value: DateTime, duration: Duration) (output: DateTime) pure
|
||
dever.time.difference(later: DateTime, earlier: DateTime) (output: Duration) pure
|
||
dever.crypto.password_hash(password: Secret) (value: Text)
|
||
dever.crypto.password_verify(password: Secret, hash: Text) (value: Bool)
|
||
dever.crypto.token(bytes: Int) (value: Secret)
|
||
dever.crypto.sha256(bytes: Bytes) (value: Bytes) pure
|
||
dever.crypto.hmac_sha256(key: Secret, bytes: Bytes) (value: Bytes) pure
|
||
dever.crypto.constant_time_eq(left: Bytes, right: Bytes) (equal: Bool) pure
|
||
```
|
||
|
||
与数字 parse 不同，时间 parse 直接返回 DateTime/Date，非法输入传播对应 `DateTimeResult.Failed` / `DateResult.Failed`；format 失败属于 TextResult。Bytes.to_text 的非法 UTF-8 传播 DecodeResult.Failed；from_ints/slice 传播 BufferResult.Failed。密码调用分别传播 HashResult/VerifyResult，token 传播 TokenResult；这些 choice 位于调用所在标准包，完整捕获使用 `result(call)` 和成功/失败分句。不要用普通 Text 打印 Secret。密码 hash/verify 在 `blocking(...)` 中执行且不能处于数据库事务内；真正写入放显式短 transaction 并重验状态。
|
||
|
||
## JSON、HTTP 与日志
|
||
|
||
```signatures
|
||
dever.json.parse(source: Text) (document: dever.json.value.Document)
|
||
dever.json.stringify(document: dever.json.value.Document) (text: Text)
|
||
dever.json.node(document: dever.json.value.Document, id: Int) (result: dever.json.value.Value?)
|
||
dever.json.property(document: dever.json.value.Document, id: Int, name: Text) (result: Int?)
|
||
dever.http.default_limits() (result: Limits)
|
||
dever.http.send(address: Text, port: Int, request: Request, limits: Limits) (response: Response)
|
||
dever.log.info(message: Text, fields: Map<Text, Text>) ()
|
||
dever.log.warn(message: Text, fields: Map<Text, Text>) ()
|
||
dever.log.error(message: Text, fields: Map<Text, Text>) ()
|
||
```
|
||
|
||
HTTP 签名的 Limits/Request/Response 是 `dever.http` 包类型。Request 字段为 `method: Text`、`target: Text`、`headers: List<dever.http.Header>`、`body: Bytes`；Header 为 `name: Text`、`value: Bytes`；Response 为 `status: Int`、`headers`、`body`。send 返回成功 Response，失败传播 ResponseResult.Failed；它是 Adapter 内的外部 I/O，不是 App 内直接请求外网的入口。自动 HTTP API 使用 App 的 wire 合同，无需拼 Request/Response。JSON parse 返回的 Document 是带 root/nodes 的类型化树，不是任意 Map；普通 API/CMD 直接使用自动 codec。
|
||
|
||
日志是同步阻塞能力；已推断为挂起的数据库 App/Job 内通过 `blocking(dever.log.info(...))` 调用，示例见 Job 的 store。不要将编译器要求的边界改成吞掉日志或数据库错误。
|
||
|
||
## 请求与权限
|
||
|
||
```signatures
|
||
dever.api.request_id() (id: Text)
|
||
dever.api.header(name: Text) (value: Text?)
|
||
dever.api.set_header(name: Text, value: Text) ()
|
||
dever.auth.id() (value: Text)
|
||
dever.auth.session() (value: Text)
|
||
dever.auth.permissions() (values: List<Permission>)
|
||
dever.auth.save_role(id: Text, name: Text, all_permissions: Bool, permission_keys: List<Text>) ()
|
||
dever.auth.disable_role(role_id: Text) ()
|
||
dever.auth.issue_cookie(subject: Text, session: Text, tenant: Text?) ()
|
||
dever.auth.clear_cookie() ()
|
||
dever.site.key() (value: Text)
|
||
```
|
||
|
||
Permission 是 `dever.auth.Permission`，字段 key/component/domain/site/action/method 均为 Text。身份读取、权限管理、请求 Header/Cookie 的入口限制仍适用，签名存在不代表任意角色可调用。敏感 Header 不能经普通 header 当 Text 读取。
|
||
|
||
以下是编译器专有操作，不按普通 library 声明中的 Int 适配桩推断业务类型：`dever.auth.user_id()` / `tenant_id()` 的结果分别是 verify Identity 对应的名义 Model ID 可空值；`grant_role(user_id, role_id)` / `revoke_role(user_id, role_id)` 的 user_id 必须是该站点的 User Model ID。不要为通过类型检查转换成裸 Int。
|
||
|
||
`dever.job.enqueue(job.name, payload, key)` 返回 Id，key 为 Text；零 payload Job 为 `enqueue(job.name, key)`。`enqueue_at` 在末尾增加 DateTime。普通测试中的 `dever.test.drain_jobs(limit: Int)` 返回 Int，`advance_clock(millis: Int)` 无输出；完整声明与调用见 [Job 项目](examples.md#持久-job)。这些静态操作不需要 import，也不能用动态字符串替代 Job 目标。
|