87 lines
6.8 KiB
Markdown
87 lines
6.8 KiB
Markdown
# 应用接口、数据与后台任务
|
||
|
||
## API 和 CMD
|
||
|
||
`module/system/health/api/admin/status.dever` 是一个可匿名访问的健康检查：
|
||
|
||
源码：[健康检查 API](../assets/examples/http-rest/module/system/health/api/admin/status.dever)
|
||
|
||
```dever
|
||
public get ready = app.status
|
||
```
|
||
|
||
API 只把请求交给 App，不写函数体。参数和返回类型直接使用 App 的声明。HTTP 支持 get/post/put/delete，不支持 patch、旧 get_ 前缀或文件内的 site 声明。
|
||
|
||
`cmd greet = app.greet` 生成 `component.domain.greet` 命令，参数是单个 JSON 对象。无需 main.dever，也无需手写命令行解析。
|
||
|
||
GET/DELETE 从 URL query 读标量参数，POST/PUT 从 JSON body 读参数。多传、重复或缺少必填字段都会报错。无需自己读 body 或构造 `dever.http.Response`。
|
||
|
||
成功返回 `{"code":0,"message":"ok","data":...}`。失败时 data 为 null，code 对应 HTTP 状态码。每个接口绑定一个能序列化的输出，输出名可自定。
|
||
|
||
`dever.api.Error` 中 Invalid/Unauthorized/Forbidden/NotFound/Conflict/TooManyRequests 对应 400/401/403/404/409/429；未知内部失败记录脱敏日志并返回安全的 500。
|
||
|
||
写 HTTP、CMD 和 Job 默认由入口建立事务；GET 不能写库或入队。
|
||
|
||
密码 hash/verify 除外：计算期间不能长期占用数据库事务。实际写入要放在显式的短 `transaction` 内，并重新检查相关状态。不要因为“默认有事务”删掉这里的短事务。
|
||
|
||
## 站点、身份与权限
|
||
|
||
`sites.admin.path = "admin"` 匹配领域内 `api/admin/**`，front 同理。文件名 topic 也进入 URL；上述 ready 是 `/system/health/admin/status/ready`。每条 HTTP 声明只能匹配一个站点，重叠或遗漏配置会失败；path 不改写 URL，也不匹配 `api/admin.dever`。
|
||
|
||
所有 HTTP 默认鉴权并校验精确权限。只有明确匿名操作写 `public post login = app.login` 等单条 public 声明；没有 public rest、public cmd、auth.require 或每个业务文件的权限注册代码。
|
||
|
||
配置中的 auth provider 指向项目自己的 `verify` App 方法，由它核实账号、会话、成员和租户关系。输入是 `dever.auth.Claims`，输出必须且只能有三个字段：
|
||
|
||
- `id: Text`：核验后的主体标识。
|
||
- `user_id: <UserModelId>?`：用户的 Model ID。
|
||
- `tenant_id: <TenantModelId>?`：租户的 Model ID。
|
||
|
||
verify 只能读 global Model，不能写库、拿原始 Header 或返回客户端自报的权限。
|
||
|
||
受保护接口认证成功后，App 可用 `dever.auth.id()`、`session()`、`user_id()`、`tenant_id()` 和 `dever.site.key()` 读取身份，不需要传 context。
|
||
|
||
这些值来自已核验的上下文，不能用客户端提交的 user_id/tenant_id 替代。ID 类型必须匹配 verify 声明，可空 ID 先用分句处理。public、CMD、Job 和普通测试不会自动获得身份读取能力。
|
||
|
||
权限键由核心生成，格式为 `component.domain.site.action`，例如 `news.article.admin.publish`。请求方法记录为元数据，不拼进权限键。REST 的 action 固定为 read/create/replace/delete。
|
||
|
||
核心已经维护角色、用户角色和角色权限表。后台 App 使用 `dever.auth.permissions/save_role/grant_role/revoke_role/disable_role` 管理授权，参数见 [签名索引](signatures.md)；这些方法只能由受保护的写 API 调用。`dever.auth.owns_user(id)` 检查资源归属，不能替代接口权限。
|
||
|
||
Cookie 登录/退出用 `dever.auth.issue_cookie(subject, session, tenant)` 与 `clear_cookie()`。Header/Cookie 使用 `dever.api` 读取/设置，无需显式 context 参数。密钥来自部署配置；Cookie 写入和 Cookie 认证的写请求需要精确同源校验，站点配置 origin。敏感头不能当普通 Text 读取。
|
||
|
||
## Model、CRUD 与业务编排
|
||
|
||
`module/content/article/model.dever` 的主记录是 Article，标题在 REST 写入时使用同领域纯计算规则：
|
||
|
||
源码：[文章 Model](../assets/examples/http-rest/module/content/article/model.dever)
|
||
|
||
```dever
|
||
type Article {
|
||
title: Text(1, 200) create = domain.normalize(input) replace = domain.normalize(input)
|
||
body: Text
|
||
}
|
||
```
|
||
|
||
自动有只读 `id` 与 `created_at`。字段支持 default、private、unique、index；范围和长度在存储边界验证。关系使用目标 Model 专有 id 字段，不用 Int 代替外键。
|
||
|
||
同领域 App 直接使用 `model.create({...})`、`model.get(id)`、`model.update(id,{...})`、`model.delete(id)` 和 `model.list({where=...,order=[created_at.desc,id.desc],page=1,size=20})`。
|
||
|
||
这些表达式由编译器检查，不是任意字典拼 SQL；无需再写 repository。关联查询和跨表插入由 App 明确编排，不会根据关系声明自动猜测级联写入顺序。
|
||
|
||
纯粹 CRUD 可在 API 写 `rest model`，多 Model 时指定 `rest model.<topic>`。Model 中 `create = expr`、`replace = expr`、`search = expr` 控制 REST 字段来源/查询；引用 input 表示客户端同名输入转换，不引用 input 表示服务端提供且禁止客户端提交。不要改成 post/put/get 字段关键字。
|
||
|
||
`private owner user_id: ... = dever.auth.user_id()` 创建时写入当前用户，并让全部读写 SQL 都带上所有权条件；它不只是隐藏输出字段。仅需这种隔离时，不用再写 App。
|
||
|
||
有关联操作、复杂输入输出、发布状态流转或超出字段约束的业务校验时，再写 App。API 中不放这些逻辑。App 用明确的 View 返回数据，避免泄漏 Model 私有字段。
|
||
|
||
不为每个 CRUD 机械建立 App、Domain、Port 和 Adapter；Model 的数据库操作无需再套一层 Port/repository。实际新增业务合同或编排时才增加对应实现。完整反重复、反硬编码及检查边界见 [项目开发](development.md)。
|
||
|
||
## 租户、任务与部署配置
|
||
|
||
配置只有 database 租户隔离：`tenant.database` 选控制连接，`global type` 使用平台库，其余持久 Model 与 Job 使用租户库。没有 field/table/mode 配置。租户缺失、未迁移或 schema 过期明确失败，不回退平台库。
|
||
|
||
运维命令：`dever tenant migrate <root> <id>`；`dever tenant owner <root> <id> <site> <user-id>` 建立核心 Owner；`dever tenant component enable|disable <root> <id> <component>` 控制租户功能。可用租户组件从 Model/Job 推导，不手写 Profile 分组。
|
||
|
||
job.dever 声明持久任务并绑定 App；enqueue 与事务、重试、调度、权限重验使用核心机制，不另写后台死循环。直接从随 skill 提供的 [Job 示例](examples.md#持久-job) 复用声明、配置和隔离测试，不能把第三方 Worker 当持久 Job。
|
||
|
||
部署配置先参考随 skill 提供的 [完整示例](examples.md)，只添加项目用到的 database、tenant、auth、sites、http、job、runtime、log。最小 CMD 项目只需模板配置。密码、token 与真实数据库连接不提交 Git。
|