openfga

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

OpenFGA Best Practices

OpenFGA最佳实践

Comprehensive guide for authoring OpenFGA authorization models and using OpenFGA SDKs, maintained for AI agents and developers. Contains rules across 7 categories covering core concepts, relationship patterns, testing, custom roles, model optimization, and language-specific SDK usage.

这是一份面向AI Agent与开发者的OpenFGA授权模型编写及OpenFGA SDK使用综合指南，涵盖8大类别规则，包括核心概念、关系定义、测试与验证、模型设计、自定义角色、模型优化、特定语言SDK使用及工作流规范。

When to Apply

适用场景

Reference these guidelines when:

Creating new OpenFGA authorization models
Defining types and relations in
```
.fga
```
files
Writing relationship tuples
Testing models with
```
.fga.yaml
```
files
Implementing custom roles
Reviewing or refactoring existing models
Integrating OpenFGA with JavaScript/TypeScript, Go, Python, Java, or .NET applications

在以下场景中可参考本指南：

创建新的OpenFGA授权模型
在
```
.fga
```
文件中定义类型与关系
编写关系元组
使用
```
.fga.yaml
```
文件测试模型
实现自定义角色
审核或重构现有模型
在JavaScript/TypeScript、Go、Python、Java或.NET应用中集成OpenFGA

Rule Categories by Priority

按优先级划分的规则类别


core-
relation-
test-
design-
roles-
optimize-
sdk-
workflow-

Priority	Category	Impact	Prefix
1	Core Concepts	CRITICAL	`core-`
2	Relationship Definitions	CRITICAL	`relation-`
3	Testing & Validation	HIGH	`test-`
4	Model Design	HIGH	`design-`
5	Custom Roles	MEDIUM	`roles-`
6	Optimization	MEDIUM	`optimize-`
7	SDK Integration	HIGH	`sdk-`
8	Workflow	CRITICAL	`workflow-`


core-
relation-
test-
design-
roles-
optimize-
sdk-
workflow-

优先级	类别	影响程度	前缀
1	核心概念	严重	`core-`
2	关系定义	严重	`relation-`
3	测试与验证	高	`test-`
4	模型设计	高	`design-`
5	自定义角色	中	`roles-`
6	优化	中	`optimize-`
7	SDK集成	高	`sdk-`
8	工作流	严重	`workflow-`

Quick Reference

快速参考

1. Core Concepts (CRITICAL)

1. 核心概念（严重）

```
core-types
```
- Define types for all entity classes
```
core-schema-version
```
- Always use schema 1.1
```
core-relations
```
- Define relations on object types, not user types
```
core-tuples
```
- Write relationship tuples to establish facts
```
core-separation
```
- Separate schema (model) from data (tuples)

```
core-types
```
- 为所有实体类定义类型
```
core-schema-version
```
- 始终使用1.1版本的Schema
```
core-relations
```
- 在对象类型而非用户类型上定义关系
```
core-tuples
```
- 编写关系元组以确立事实
```
core-separation
```
- 将Schema（模型）与数据（元组）分离

2. Relationship Definitions (CRITICAL)

2. 关系定义（严重）

```
relation-direct
```
- Use
```
[type]
```
for direct assignments
```
relation-concentric
```
- Use
```
or
```
for permission inheritance
```
relation-indirect
```
- Use
```
X from Y
```
for hierarchical access
```
relation-usersets
```
- Use
```
type#relation
```
for group-based access
```
relation-conditions
```
- Use CEL conditions for contextual authorization
```
relation-wildcards
```
- Use
```
type:*
```
for public access carefully
```
relation-wildcards-as-booleans
```
- To use
```
type:*
```
to model boolan attributes

```
relation-direct
```
- 使用
```
[type]
```
进行直接分配
```
relation-concentric
```
- 使用
```
or
```
实现权限继承
```
relation-indirect
```
- 使用
```
X from Y
```
实现层级访问
```
relation-usersets
```
- 使用
```
type#relation
```
实现基于组的访问
```
relation-conditions
```
- 使用CEL条件实现上下文授权
```
relation-wildcards
```
- 谨慎使用
```
type:*
```
实现公共访问
```
relation-wildcards-as-booleans
```
- 使用
```
type:*
```
模拟布尔属性

3. Model Design (HIGH)

3. 模型设计（高）

```
design-permissions
```
- Define
```
can_*
```
relations for permissions
```
design-hierarchy
```
- Model parent-child relationships correctly
```
design-organization
```
- Structure organization-level access
```
design-naming
```
- Use clear, consistent naming conventions
```
design-modules
```
- Split a model in modules for collaboration among multiple teams.

```
design-permissions
```
- 为权限定义
```
can_*
```
关系
```
design-hierarchy
```
- 正确建模父子关系
```
design-organization
```
- 构建组织级访问结构
```
design-naming
```
- 使用清晰、一致的命名规范
```
design-modules
```
- 将模型拆分为模块以支持多团队协作

4. Testing & Validation (HIGH)

4. 测试与验证（高）

```
test-fga-yaml
```
- Structure tests in
```
.fga.yaml
```
files
```
test-check-assertions
```
- Write check assertions for permission verification
```
test-list-objects
```
- Test list_objects queries
```
test-list-users
```
- Test list_users queries
```
test-conditions
```
- Test conditional relationships with context
```
test-cli
```
- Use OpenFGA CLI for model testing

```
test-fga-yaml
```
- 在
```
.fga.yaml
```
文件中构建测试结构
```
test-check-assertions
```
- 编写检查断言以验证权限
```
test-list-objects
```
- 测试list_objects查询
```
test-list-users
```
- 测试list_users查询
```
test-conditions
```
- 结合上下文测试条件关系
```
test-cli
```
- 使用OpenFGA CLI进行模型测试

5. Custom Roles (MEDIUM)

5. 自定义角色（中）

```
roles-simple
```
- Implement simple user-defined roles
```
roles-assignments
```
- Use role assignments for resource-specific roles
```
roles-static-combo
```
- Combine static and custom roles
```
roles-when-to-use
```
- Choose the right role pattern

```
roles-simple
```
- 实现简单的用户自定义角色
```
roles-assignments
```
- 使用角色分配实现资源特定角色
```
roles-static-combo
```
- 组合静态角色与自定义角色
```
roles-when-to-use
```
- 选择合适的角色模式

6. Optimization (MEDIUM)

6. 优化（中）

```
optimize-simplify
```
- Remove unused types and relations
```
optimize-tuples
```
- Use indirect relationships to reduce tuple count
```
optimize-type-restrictions
```
- Apply appropriate type restrictions

```
optimize-simplify
```
- 移除未使用的类型与关系
```
optimize-tuples
```
- 使用间接关系减少元组数量
```
optimize-type-restrictions
```
- 应用适当的类型限制

7. SDK Integration (HIGH)

7. SDK集成（高）

```
sdk-javascript
```
- JavaScript/TypeScript SDK usage
```
sdk-go
```
- Go SDK usage
```
sdk-python
```
- Python SDK usage (async and sync)
```
sdk-java
```
- Java SDK usage
```
sdk-dotnet
```
- .NET SDK usage

```
sdk-javascript
```
- JavaScript/TypeScript SDK使用
```
sdk-go
```
- Go SDK使用
```
sdk-python
```
- Python SDK使用（异步与同步）
```
sdk-java
```
- Java SDK使用
```
sdk-dotnet
```
- .NET SDK使用

8. Workflow (CRITICAL)

8. 工作流（严重）

```
workflow-validate
```
- Always validate models before delivery

```
workflow-validate
```
- 交付前始终验证模型

How to Use

使用方法

Read individual rule files for detailed explanations and code examples:

rules/core-types.md
rules/relation-concentric.md
rules/test-fga-yaml.md

Each rule file contains:

Brief explanation of why it matters
Incorrect code example with explanation
Correct code example with explanation
Additional context and references

阅读单个规则文件以获取详细说明及代码示例：

rules/core-types.md
rules/relation-concentric.md
rules/test-fga-yaml.md

每个规则文件包含：

规则重要性的简要说明
错误代码示例及解释
正确代码示例及解释
额外上下文与参考资料

Full Compiled Document

完整编译文档

For the complete guide with all rules expanded:

AGENTS.md

如需查看包含所有展开规则的完整指南，请查阅：

AGENTS.md