接口授权与权限定义
约 916 字大约 3 分钟
2025-03-03
平台权限至少包含“身份是否可信”“能否执行此动作”“能否操作这条数据”三层。菜单和按钮不是后端安全边界，本页说明如何把动作合同写进平台 .api 并同步到路由权限。
设计资源和动作
先按业务资源确定稳定编码，再定义 view、create、update、delete 或业务专用动作。读详情与读列表通常都使用 view，不因 HTTP 使用 POST 就误标成写权限。
| 问题 | 定义位置 |
|---|---|
| 谁可以登录调用 | authType 与认证中间件 |
| 允许访问哪个资源/动作 | resource、action 与角色权限 |
| 能操作哪个企业/项目/设备 | logic、领域与仓储过滤 |
| 是否展示菜单/按钮 | 平台前端菜单与动作权限 |
在合同声明权限
下面为示意定义，类型需要放入本服务 .api，动作编码沿用所属模块现行字典：
@doc (
summary: "读取业务详情"
description: "业务说明：按对象编号读取当前企业有权访问的业务详情。"
authType: "all"
resource: "demoInfo"
action: "view"
group: "业务示例"
recordLogMode: "1"
)
@handler getOne
post /get-one (DemoGetOneReq) returns (DemoInfo)authType 选择服务已有支持值，例如普通用户、管理员或平台管理员的对应配置，不能随意造字符串。资源和动作必须与前端授权使用一致；recordLogMode 按同组接口与生成器规则配置。
旧文中的 isNeedAuth、businessType 等不能代替当前 @doc 元数据。不要为了通过生成器检查填一个与业务无关的通用资源。
生成、同步与初始化
- 修改原始
.api，执行该服务build.sh。 - 检查生成路由及 Swagger 中动作与认证信息正确。
- 按服务已有启动流程将路由资源幂等同步到平台，保持稳定编码。
- 为应用、角色和菜单绑定需要的资源权限，验证新旧角色结果。
- 如需公开 SDK，按合同维护同步客户端。
当前服务的路由资源生成及启动同步入口以现有实现为准，不把历史 access.json 流程概括为全部服务通用步骤。权限数据变化需要代码内幂等迁移/种子同步，不能只要求用户手工改表。
数据权限不能省略
即使动作允许，按 ID 读取/更新前仍要检查企业和业务归属；设备控制还需验证项目、区域或分享权限。接口既不能因用户持有 token 就放行，也不能只靠客户端不展示其他企业的数据。
项目选择头表达用户当前想访问的项目，服务端需要计算它是否有权访问。详细规则见项目与区域数据权限。
典型验收
- 同一角色的只读、创建、修改权限分别验证；只读角色不能构造写请求。
- 普通成员直接打开菜单 URL 与直接调用 API 的结果一致。
- 变更授权/撤销后，缓存和已有连接按预期收敛。
- 跨企业/项目 ID 和不存在对象得到正确错误，不泄漏其他范围数据。
- 开放令牌按绑定用户实际权限执行，不统一视作管理员。
影响旧端接口时，继续核对 apilegacy 的认证、错误码和 ID 序列化，不能只验证新管理端。
更新日志
2026/10/16 20:08
查看所有更新日志
b1437-docs(应用开发): 补齐WS通知及平台能力接入导航于b3b4d-docs(平台开发): 恢复有效专题并更新当前实现示例于