跳到主要内容

API 与鉴权导读

完整契约以仓库为准：

  • 人类可读：docs/api.md
  • 机器可读：docs/openapi/openapi.yaml
  • 权限：docs/permissions.md、docs/rbac.md
  • 安全：docs/security.md

本页帮助你快速建立读 API 的地图。

1. API 的组织方式​

  • 面向产品的 HTTP API 多以 /v1/... 为前缀（以 OpenAPI 为准）
  • 业务按组织（organization）作用域隔离：多数资源挂在组织下
  • 内部管理 API 常在 /internal/admin/*，默认关闭，且必须强鉴权

读一个模块时，建议顺序：

  1. OpenAPI 或 docs/api.md 中的分组
  2. 对应 services/{module}/adapter/http
  3. application 用例
  4. 需要跨模块时看 libs/contracts

2. 用户鉴权（控制面）​

典型能力（名称随版本变化）：

  • 注册 / 登录 / 会话
  • 邮箱验证、密码重置
  • 组织成员与邀请
  • 基于角色的组织内权限检查

调用业务 API 前：

  1. 完成登录拿到会话/令牌（Cookie 或 Bearer，以文档为准）
  2. 明确当前组织上下文
  3. 确认角色是否具备对应 permission

本地可用 smoke 或仓库提供的 demo 流程验证「登录 → 调一个组织 API」。

3. 设备鉴权（数据/传输面）​

设备侧不是用户 Cookie 那一套，常见是：

  • 设备凭证（key/secret 等，入库加密/pepper）
  • MQTT 用户名密码与 topic 前缀
  • 命令拉取与 ack 的设备身份

详见仓库：

  • docs/devices.md
  • docs/device-mqtt-access.md
  • docs/commands.md

4. ID、分页与错误​

阅读 OpenAPI 时注意：

  • ID 表示形式（雪花/字符串等）
  • 游标分页字段与密钥（如 GOSTARTKIT_CURSOR_SECRET）
  • 错误体结构与业务错误码

实现新接口时，错误语义与幂等约定可对照本站 API 设计边界 与仓库安全文档。

5. 权限模型直觉​

  • 组织内角色决定能看/能改哪些资源
  • 服务端必须做对象级授权，不能只靠「藏菜单」
  • 管理端平台角色与组织角色分离

改权限矩阵时，同步更新文档与测试，避免「前端隐藏、API 裸奔」。

6. 本地探索建议​

make run-monolith
# 按 docs/api.md 或 OpenAPI 调用登录与健康检查
make smoke

需要真实设备链路时，再打开 MQTT 与 simulator 文档。

下一步：构建与部署。