65 lines
4.3 KiB
Markdown
65 lines
4.3 KiB
Markdown
# 应用
|
||
|
||
## API 和 CMD
|
||
|
||
源码：[健康检查 API](../assets/examples/http-rest/module/system/health/api/admin/status.dever)
|
||
|
||
```dever
|
||
public get ready = app.status
|
||
```
|
||
|
||
API 只绑定同领域 App 或声明 REST。支持 get/post/put/delete；CMD 写 `cmd name = app.function`。输入输出继承 App，每个接口绑定一个可序列化输出。
|
||
|
||
GET/DELETE 从 query 读标量，POST/PUT 从 JSON 对象读参数。未知、重复或缺少必填字段失败。成功为 `{"code":0,"message":"ok","data":...}`；失败的 code 对应 HTTP 状态，data 为 null。dever.api.Error 映射 400/401/403/404/409/429，内部故障返回安全的 500。
|
||
|
||
## 站点、身份与权限
|
||
|
||
`sites.admin.path = "admin"` 匹配 api/admin/**；文件主题也进入 URL，上例为 /system/health/admin/status/ready。每条 HTTP 声明恰好匹配一个站点；path 不重写 URL，也不匹配 api/admin.dever。
|
||
|
||
| 声明 | 校验 |
|
||
| --- | --- |
|
||
| 默认 HTTP | 身份与精确角色权限 |
|
||
| public HTTP | 匿名入口 |
|
||
| authenticated HTTP | 可信身份；App 校验对象所有权和实际业务权限 |
|
||
|
||
public/authenticated 不修饰 CMD 或 REST。权限键由核心生成，为 component.domain.site.action；REST 使用 read/create/replace/delete，方法不进入键。
|
||
|
||
Provider 的 verify App 接收 dever.auth.Claims，只返回 id: Text、user_id: UserModelId?、tenant_id: TenantModelId?。它读取 global Model 核验账号、会话、成员和租户，不返回权限列表。
|
||
|
||
认证后使用 dever.auth 和 dever.site 读取可信身份，Model ID 须匹配 verify。客户端数据不作为身份来源。public、CMD、Job 和普通测试不能直接读取 HTTP 身份。
|
||
|
||
核心管理角色、用户角色和权限，读取允许受保护及 authenticated 入口，修改仅允许普通受保护写入口。通用业务权限使用 registerCapability/removeCapability，命名空间与租户来自可信入口。方法见 [签名](signatures.md)。
|
||
|
||
Cookie 登录/退出使用 issueCookie/clearCookie；配置站点 origin，Cookie 写入及 Cookie 认证的写请求校验 Origin 和 Host。敏感头不读作普通 Text。
|
||
|
||
## Model 与业务操作
|
||
|
||
源码：[文章 Model](../assets/examples/http-rest/module/content/article/model.dever)
|
||
|
||
```dever
|
||
type Article {
|
||
title: Text(1, 200)
|
||
body: Text raw
|
||
}
|
||
```
|
||
|
||
Model 自动生成只读 id 和 created_at，字段支持 default/private/unique/index。不同 Model 的 ID 不混用。
|
||
|
||
Model Text 写入时默认去除首尾 Unicode 空白，再校验长度；`raw` 保留原文，`lower`/`upper` 在去空白后转换大小写，三者互斥。null 不变，空串不转 null。普通 Text、查询和原生 SQL 不自动转换。正文、代码等用 raw；用户名可以用 lower，但登录查询仍由业务明确采用同一规范。唯一性使用数据库 unique，不能先查询代替约束。
|
||
|
||
普通 CRUD 直接写 rest model；多 Model 指定 model.topic。App 使用 model.create/get/list/update/delete 等操作，字段和查询由编译器检查，值参数绑定。
|
||
|
||
REST 的 create/replace/search 表达式引用 input 时转换客户端输入，否则由服务端提供并拒绝客户端同名字段。private owner 使用可信用户绑定全部读写 SQL。
|
||
|
||
有关联操作、状态变化或额外输入输出转换再写 App。Model 数据库操作不套 Port/repository，私有字段通过显式 View 隐藏。
|
||
|
||
## 事务、租户与 Job
|
||
|
||
普通写 HTTP、CMD、Job 建立整体事务，成功编码后提交。GET 不写库或入队。外部 I/O、Worker、密码计算和并发放事务外；需要分阶段编排时用 long 入口，写入进入显式 transaction。事务内重查写入依赖的状态；先前提交的阶段不因后续失败撤销。
|
||
|
||
tenant.database 选择控制连接，global type 使用平台库，其余 Model/Job 使用租户库。只支持 database 隔离；缺少租户或 schema 未就绪时报错。
|
||
|
||
部署侧用 dever tenant migrate、tenant owner、tenant component enable/disable 管理租户。Job 按 [示例](examples.md#持久-job)声明，由核心负责队列、重试和执行前权限重验。
|
||
|
||
配置只加实际用到的 database、tenant、auth、sites、http、job、runtime、log。完整配置见 [HTTP 项目](../assets/examples/http-rest/config/setting.json)和 [Job 项目](../assets/examples/jobs/config/setting.json)；示例占位凭据须替换，真实秘密不提交。
|