openfga

OpenFGA 最佳实践

使用此技能从头到尾设计和审查 OpenFGA 模型：定义类型和关系，编写元组，推导 can_* 权限，选择 userset 和继承模式，并通过 .fga.yaml 测试和 CLI 检查验证行为。

快速入门示例

最小模型：

model
  schema 1.1

type user

type organization
  relations
    define admin: [user]
    define member: [user] or admin

type document
  relations
    define organization: [organization]
    define owner: [user]
    define can_edit: owner or admin from organization
    define can_view: can_edit or member from organization

示例元组：

organization:acme#admin@user:alice
document:roadmap#organization@organization:acme
document:roadmap#owner@user:bob

示例测试目标：

• check 检查 user:alice 是否可以查看和编辑 document:roadmap
• check 检查 user:bob 是否可以编辑自己的文档
• list_users 列出 document:roadmap#can_view 对应的用户
• list_objects 列出 user:alice 可以编辑的文档

如何使用

如果工作流步骤指向规则 ID，请打开 references/ 中对应的文件，查看详细指导和示例。

注意： SDK 参考（sdk-*.md）仅用于集成任务——纯模型编写和测试时请跳过。

规则索引

核心

文件	描述
references/core-types.md	定义实体类别的类型
references/core-relations.md	关系应定义在对象类型上
references/core-tuples.md	将关系元组作为事实
references/core-separation.md	模型与数据分离
references/core-schema-version.md	架构版本

关系

文件	描述
references/relation-direct.md	直接关系
references/relation-indirect.md	使用“Y 中的 X”的间接关系
references/relation-concentric.md	同心关系
references/relation-usersets.md	用于基于群组的访问控制的 userset
references/relation-conditions.md	条件关系
references/relation-wildcards.md	用于公开访问的通配符
references/relation-wildcards-as-booleans.md	用于布尔属性的通配符

设计

文件	描述
references/design-permissions.md	使用 can_ 关系定义权限
references/design-hierarchy.md	层级结构
references/design-organization.md	组织级访问控制
references/design-create-on-parent.md	检查父对象上的创建权限
references/design-naming.md	命名约定
references/design-modules.md	将模型模块化（仅在提出要求时）

角色

文件	描述
references/roles-simple.md	简单的静态角色
references/roles-static-combo.md	组合静态角色和自定义角色
references/roles-assignments.md	用于资源特定角色的角色分配
references/roles-when-to-use.md	何时使用各种角色模式

优化

文件	描述
references/optimize-simplify.md	简化模型
references/optimize-tuples.md	尽量减少元组数量
references/optimize-type-restrictions.md	类型限制

测试

文件	描述
references/test-fga-yaml.md	在 .fga.yaml 中组织测试
references/test-check-assertions.md	检查断言
references/test-list-objects.md	列出对象的测试
references/test-list-users.md	列出用户的测试
references/test-conditions.md	测试条件
references/test-cli.md	OpenFGA CLI 用法
references/workflow-validate.md	始终验证模型

SDK（仅用于集成任务）

文件	描述
references/sdk-javascript.md	JavaScript/TypeScript SDK
references/sdk-go.md	Go SDK
references/sdk-python.md	Python SDK
references/sdk-java.md	Java SDK
references/sdk-dotnet.md	.NET SDK

推荐的工作流

1. 建模资源图。 定义类型、直接关系、继承边和 can_* 权限。 优先检查的规则：core-*、relation-*、design-permissions、design-hierarchy。

2. 添加元组并测试意图。 添加有代表性的元组，并使用 check、list_objects 和 list_users 测试预期行为。 接下来检查的规则：core-tuples、test-fga-yaml、test-check-assertions、test-list-objects、test-list-users。

3. 检查父子项的创建和删除路径。 确认每条 parent -> child 边都在父项上具有创建权限，并且除非有意如此，否则子项权限不能被直接授予。 要检查的规则：design-create-on-parent、relation-direct、design-permissions。

4. 删除架构前先简化。 删除任何类型或关系之前，确认权限、元组或测试没有引用它。 如果简化导致引用失效：恢复该关系或更新模型/测试，然后重新执行此步骤。 要检查的规则：optimize-simplify、optimize-tuples、optimize-type-restrictions。

5. 验证模型。 运行：

fga model validate --file stores/<store>/model.fga

如果验证失败：查看报告的关系或类型错误，修复模型，然后继续之前重新运行验证。

6. 运行存储测试。 运行：

fga model test --tests stores/<store>/store.fga.yaml

如果测试失败：更新元组、断言或权限定义，然后重新运行测试，直到所有检查和列表查询都通过。

7. 仅在此之后完成交付。 对于已修改的存储，只有在验证和测试均通过后才能完成。 最后要检查的规则：workflow-validate。

完整编译文档

查看包含所有展开规则的完整指南：AGENTS.md