123 lines
6.9 KiB
Markdown
123 lines
6.9 KiB
Markdown
# 标准库常用签名
|
||
|
||
参数按位置传入，输出名属于合同。以下签名与随包 lib/ 的公开声明由 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.startsWith(value: Text, prefix: Text) (result: Bool)
|
||
text.endsWith(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.toText(value: Int) (result: Text)
|
||
decimal.parse(value: Text) (result: Decimal?)
|
||
decimal.round(value: Decimal, places: Int) (result: Decimal)
|
||
decimal.fromInt(value: Int) (result: Decimal)
|
||
decimal.toText(value: Decimal) (result: Text)
|
||
float.parse(value: Text) (result: Float?)
|
||
float.fromInt(value: Int) (result: Float)
|
||
uuid.parse(value: Text) (result: Uuid?)
|
||
uuid.toText(value: Uuid) (result: Text)
|
||
dever.id.fromText(text: Text) (id: Id)
|
||
dever.id.toText(id: Id) (text: Text)
|
||
```
|
||
|
||
数值和 Uuid 的 parse 失败返回 null。Id、Uuid、Model ID 是不同类型。Text 索引按 Unicode 码点，slice 含起点、不含终点。
|
||
|
||
## Bytes、时间与密码
|
||
|
||
```signatures
|
||
dever.bytes.fromText(text: Text) (bytes: Bytes)
|
||
dever.bytes.toText(bytes: Bytes) (text: Text)
|
||
dever.bytes.fromInts(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.parseDatetime(text: Text) (output: DateTime) pure
|
||
dever.time.formatDatetime(value: DateTime) (output: Text) pure
|
||
dever.time.parseDate(text: Text) (output: Date) pure
|
||
dever.time.formatDate(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.passwordHash(password: Secret) (value: Text)
|
||
dever.crypto.passwordVerify(password: Secret, hash: Text) (value: Bool)
|
||
dever.crypto.token(bytes: Int) (value: Secret)
|
||
dever.crypto.sha256(bytes: Bytes) (value: Bytes) pure
|
||
dever.crypto.hmacSha256(key: Secret, bytes: Bytes) (value: Bytes) pure
|
||
dever.crypto.constantTimeEq(left: Bytes, right: Bytes) (equal: Bool) pure
|
||
```
|
||
|
||
时间解析失败传播 DateTimeResult/DateResult，格式化失败传播 TextResult。非法 UTF-8 为 DecodeResult，字节范围错误为 BufferResult。密码与 token 分别传播 HashResult/VerifyResult/TokenResult；用 result 捕获。密码计算放事务外，在挂起调用链中使用 blocking。
|
||
|
||
## JSON 与 HTTP
|
||
|
||
```signatures
|
||
dever.json.fromText(source: Text) (value: Json)
|
||
dever.json.toText(value: Json) (source: Text)
|
||
dever.json.setProperty(value: Json, name: Text, child: Json) (result: Json)
|
||
dever.json.propertyValue(value: Json, name: Text) (result: Json?)
|
||
dever.json.asText(value: Json) (source: Text)
|
||
dever.json.asInteger(value: Json) (number: Int)
|
||
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) (value: dever.json.value.Value?)
|
||
dever.json.property(document: dever.json.value.Document, id: Int, name: Text) (value: Int?)
|
||
dever.http.defaultLimits() (result: Limits)
|
||
dever.http.send(address: Text, port: Int, request: Request, limits: Limits) (response: Response)
|
||
```
|
||
|
||
Json 是不透明值，fromText/toText 保留原始 JSON；propertyValue 返回子 Json。普通 API/CMD 自动编解码。已有 Json 转具体类型用 `dever.json.decode(value)`，由局部类型声明、命名输出、字段或参数确定类型；直接复用 Serde 解码，失败传播 JsonResult.Failed。需要捕获时直接使用 `result(dever.json.decode(value))`，结果 Choice 的成功字段提供目标类型，error 分支包装 JsonResult。不要先转 Text、Document 再手工组装已知类型。未知结构才使用 Document 的 root/nodes 节点树。
|
||
|
||
HTTP 的 Limits/Request/Response 属于 dever.http。Request 有 method/target: Text、headers: List<Header>、body: Bytes；Header 有 name: Text、value: Bytes，Response 有 status: Int、headers、body。send 在 Adapter 使用，失败传播 ResponseResult.Failed。
|
||
|
||
日志由运行时和部署配置管理，当前标准库没有 dever.log 源码接口。
|
||
|
||
## 请求与权限
|
||
|
||
```signatures
|
||
dever.api.requestId() (value: Text)
|
||
dever.api.header(name: Text) (value: Text?)
|
||
dever.api.setHeader(name: Text, value: Text) ()
|
||
dever.auth.id() (value: Text)
|
||
dever.auth.session() (value: Text)
|
||
dever.auth.permissions() (values: List<Permission>)
|
||
dever.auth.currentPermissions() (values: List<Permission>)
|
||
dever.auth.roles() (values: List<Role>)
|
||
dever.auth.role(id: Text) (value: Role?)
|
||
dever.auth.userRoles(user_id: Int) (values: List<Role>)
|
||
dever.auth.isOwner(user_id: Int) (value: Bool)
|
||
dever.auth.hasProtectedRoles(user_id: Int) (value: Bool)
|
||
dever.auth.registerCapability(id: Uuid) (key: Text)
|
||
dever.auth.removeCapability(id: Uuid) ()
|
||
dever.auth.saveRole(id: Text, name: Text, all_permissions: Bool, permission_keys: List<Text>) ()
|
||
dever.auth.grantRole(user_id: Int, role_id: Text) ()
|
||
dever.auth.revokeRole(user_id: Int, role_id: Text) ()
|
||
dever.auth.disableRole(role_id: Text) ()
|
||
dever.auth.deleteRole(role_id: Text) ()
|
||
dever.auth.issueCookie(subject: Text, session: Text, tenant: Text?) ()
|
||
dever.auth.clearCookie() ()
|
||
dever.site.key() (value: Text)
|
||
```
|
||
|
||
`dever.api.require(condition, error)` 接受 Bool 条件和 dever.api.Error；false 时失败，true 时继续。
|
||
|
||
Permission 的 key/component/domain/site/action/method/kind 均为 Text；kind 为 http 或 capability，后者 method 为空、action 为 UUID。Role 有 id/site/name: Text、all_permissions/enabled/protected: Bool、permission_keys: List<Text>。
|
||
|
||
授权读取允许受保护或 authenticated 入口，修改仅允许普通受保护写入口。capability 还要求可信租户，返回 capability:<component>.<domain>.<site>.<uuid>。isOwner 查询当前站点，hasProtectedRoles 查询当前租户全部站点。访问边界见 [应用](application.md)。
|
||
|
||
dever.auth.userId()/tenantId() 可按上下文产生 verify 对应的可空名义 ID。角色操作的目标 user_id 为 Int，只标识当前租户内的对象，不替代操作者身份。
|
||
|
||
dever.job.enqueue(job.name[, payload], key) 返回 Id；enqueueAt 末尾加 DateTime。测试的 drainJobs(limit) 返回 Int，advanceClock(ms) 无输出。见 [Job 示例](examples.md#持久-job)。
|