socar-api 0.6.0__tar.gz

socar_api-0.6.0/PKG-INFO

@@ -0,0 +1,177 @@
+Metadata-Version: 2.4
+Name: socar-api
+Version: 0.6.0
+Summary: 基于 FastAPI + JSON:API 规范的 RESTful 接口框架
+Author-email: "so.car" <socar@so.car>
+License-Expression: MIT
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: fastapi>=0.136.3
+Requires-Dist: pydantic>=2.13.4
+Requires-Dist: jquery-unparam>=2.0.0
+Requires-Dist: pyyaml>=6.0.3
+Requires-Dist: treelib>=1.8.0
+Requires-Dist: bitarray>=3.8.1
+Requires-Dist: python-multipart>=0.0.32
+Requires-Dist: python-dateutil>=2.9.0.post0
+Requires-Dist: typing-extensions>=4.15.0
+Provides-Extra: dev
+Requires-Dist: pytest>=9.0.3; extra == "dev"
+Requires-Dist: pytest-asyncio>=1.4.0; extra == "dev"
+Requires-Dist: httpx>=0.28.1; extra == "dev"
+Requires-Dist: pytest-cov>=7.1.0; extra == "dev"
+Requires-Dist: ruff>=0.15.16; extra == "dev"
+Requires-Dist: mypy>=2.1.0; extra == "dev"
+Requires-Dist: pre-commit>=4.6.0; extra == "dev"
+
+# api_frame
+
+基于 FastAPI + JSON:API 规范的 RESTful 接口框架。
+
+[![version](https://img.shields.io/badge/version-0.6.0-blue.svg)](https://gitee.com/socar/api_frame)
+
+## 简介
+
+api_frame 提供了从资源声明 → 路由生成 → 请求处理 → 响应序列化的完整链路，让开发者**专注业务逻辑**，无需重复实现接口规范。
+
+框架提供两种资源基类：
+- **`BaseResource`** — 完整基类，支持 `connect_data()` session 管理和子资源嵌套
+- **`Resource`**（推荐） — 简化基类，内置 JSON:API 序列化管线，可直接访问 `self.db`
+
+```python
+from api_frame import Resource, SchemaBase, Field, Relationship
+
+class ArticleModel(SchemaBase):
+    title: str = Field(None)
+    content: str = Field(None)
+    author_id: int = Field(None, isrel=True)
+
+class Article(Resource):
+    model = ArticleModel
+
+    class Meta:
+        link = '/articles'
+        type_ = 'articles'
+
+    class RelResources:
+        author = Relationship(
+            rel_resource='Author',
+            mapping_field='author_id',
+            has_api=False,
+        )
+
+    async def get_many(self):
+        return self.db.query(ArticleModel).all()
+
+    async def post(self):
+        body = self.parse_body()
+        obj = ArticleModel(**body.model_dump())
+        self.db.add(obj)
+        self.db.commit()
+        return self.model.model_validate(obj)
+```
+
+一行 `Article.register_routes(app)` 即生成完整 JSON:API 接口。
+
+## 核心特性
+
+- **JSON:API 规范** — 请求/响应格式、资源关系、稀疏字段、include 复合文档、分页
+- **资源路由** — 类声明式路由，自动生成标准 CRUD 端点
+- **关系管理** — 一对一/一对多关系，include 深层级联（最多支持 3 层）
+- **权限系统** — 基于 scope 的 OAuth2 认证，API + 关系双层权限；支持 `@scope` 声明式配置
+- **原子操作** — JSON:API Atomic 扩展支持，批量操作 + 事务回滚
+- **文件上传/下载** — 增强的 `UploadFileResource` / `DownloadFileResource` 基类，文件类型验证、关系校验、可替换存储后端
+- **响应缓存** — `@cached()` 装饰器一行启用接口缓存，Cache-Aside 模式，可替换后端
+- **筛选过滤** — Deep Object 格式，40+ 操作符覆盖字符串/数值/列表/时间/布尔
+- **自动模型** — 根据资源自动生成请求/响应模型
+- **资源版本** — 内建 API 版本管理
+- **自动文档** — 与 FastAPI OpenAPI 集成
+
+## 安装
+
+> **要求**: Python 3.12+
+
+```bash
+pip install git+https://gitee.com/socar/api_frame
+```
+
+## 快速开始
+
+```python
+from fastapi import FastAPI
+from api_frame import BaseResource, SchemaBase, Field
+from api_frame.util import register_jsonapi_exception_handlers
+
+
+class BookModel(SchemaBase):
+    id: str = Field(None)
+    title: str = Field(None)
+    author: str = Field(None)
+
+
+class Book(BaseResource):
+    model = BookModel
+    methods = {'GET', 'GETS', 'POST', 'PATCH', 'DELETE'}
+
+    class Meta:
+        link = '/books'
+        type_ = 'books'
+
+
+app = FastAPI()
+register_jsonapi_exception_handlers(app)
+Book.register_routes(app)
+```
+
+启动后自动生成：
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| `GET` | `/books` | 资源列表 |
+| `GET` | `/books/{id}` | 单个资源 |
+| `POST` | `/books` | 新增资源 |
+| `PATCH` | `/books/{id}` | 更新资源 |
+| `DELETE` | `/books/{id}` | 删除资源 |
+| `POST` | `/atomic` | 原子操作（`register_routes()` 自动注册） |
+
+## 文档
+
+- [框架概述 & 核心概念](docs/index.md)
+- [快速开始指南](docs/guide.md)
+- [API 参考](docs/api.md)
+- [原子操作设计文档](docs/atomic.md)
+
+## 安装指定版本
+
+```bash
+pip install git+https://gitee.com/socar/api_frame.git@v0.6.0
+```
+
+## 版本历史
+
+| 版本 | 说明 |
+|------|------|
+| v0.6.0 | 声明式 scope 配置 (`@scope`)、增强文件上传/下载基类 (`filebase.py`)、统一缓存装饰器 (`@cached`)、SecurityConfig strict 模式。405 tests |
+| v0.5.11 | `create_filter_model` 处理 `typing.Union`（`Optional[X]`）；`page[limit]`/`page[offset]` 解析后转为 `int`。330 tests |
+| v0.5.10 | `relapi=False` 时不生成 relationship links；`has_self_link` 控制 `data.links.self`；顶层 `links.self` 保留原始 request URL 的全部 query params；分页导航 `first/last/prev/next` 保留 `filter/sort/include` 等非分页参数；`get_host()` 不再硬编码 HTTPS，保留实际请求协议。325 tests |
+| v0.5.9 | UploadFileBaseResource `examples` list 格式 + `e.raw_errors→e.errors()`（Pydantic v2 兼容）；include 兄弟节点 `asyncio.gather` 并行；Schema cache double-lookup 优化（13 处）；`list[tuple]→Union` 修复（Pydantic v2 homogeneous list 退化）；`_build_response` / `_jsonapi` 单资源 `links.self` 含 ID（含 BaseResource 路径修复）；NumberFilter/FloatFilter 增加 `aeq`；306 tests |
+| v0.5.8 | JSON:API v1.1 合规全闭环（POST Location 头、PATCH body.id 409 校验、422 JSON Pointer `source.pointer`、顶层 `links.self` 含 ID、include 保留连字符、查询参数命名约定、分页 `links.first/last/prev/next` URL）；`lid` 支持（ResourceIdentifier/RelationshipModel/ApiDataModelRequest）；filter NumberFilter/FloatFilter 增加 `aeq` 操作符；query.py dict 类型检测兼容 Python 3.12（`__origin__ is dict`）；`list[tuple(...)]` → Union（Pydantic v2 退化为 homogeneous list 修复）；exception.py 空 parts JSON Pointer 边界保护；`_build_response` 单资源 `links.self` 正确提取 ID；303 tests |
+| v0.5.7 | resource.py _jsonapi 新增 `many` 参数，空结果根据 many 返回 `[]` 或 `null`；handlers.py make_related_handler 对 to-one 404 自动转换为 `data: null`（修复 `/models/{id}/measure` 等 related 端点 500）；292 tests |
+| v0.5.6 | filter.py: UnionType (`int\|None`) + GenericAlias (`list[str]`) 支持；serializer.py: None to-one 关系产出 null 标识符；query.py: Filters/ArgsModel 的 get_field_value/get_filter/pop_and_filter 递归遍历 FilterOr；移除根目录残留 `__init__.py`；292 tests |
+| v0.5.4 | JSON:API v1.1 合规收紧（ErrorModel.status str 强制 + field_validator 自动 int→str；ResourceIdentifier.id/type 必填不可空；ErrorResponse model_dump 默认 exclude_none）；RefRes.id 统一 str；status 校验增加 bool 拒绝 + HTTP 100-599 区间；ResourceIdentifier validator mode=before + whitespace strip 自动规范化；新增边界测试覆盖空白 id、status 区间边界；292 tests |
+| v0.5.3 | JSON:API v1.1 合规改进（ErrorModel/ErrorResponse/LinksSelfModel 扩展 v1.1 字段）；related_cond/serializer request 传递 bug 修复；ApiDataModelResponse.id 类型收紧；get_field_value 类型注解修正 + ArgsModel 多值一致性；jsonapi.version → 1.1；LinksRelatedModel 补全 href/meta；OpenAPI summary 自然中文描述 + 资源类型前缀；清除废弃注释代码和构建残留；415/406 Content-Type/Accept 校验中间件 JSONAPIContentNegotiationMiddleware；移除废弃 Pydantic v1 兼容层（Meta.dict → model_dump、__fields__ → model_fields）；RdentifierMeta → IdentifierMeta 正名；过期 warning 升级为 error；StrEnum / PEP 695 语法迁移；examples/ 全面清理；filterwarnings 移除；mypy 严格模式；requires-python ≥3.12；新增 31 合规补集测试（共 289 pass） |
+| v0.5.0 | Pydantic v2 原生迁移；resource.py 拆分为 router/serializer/handlers/atomic 四模块；新增简化基类 Resource；Python 3.10+ 语法（`int | str` 替代 `Union`）；FastAPI 0.136；移除 clean.py、build/；OpenAPI summary 优化 |
+| v0.4.0 | 原子操作 Atomic 支持、权限三态模型（未配 scope = 放行）、docs 文档 |
+| v0.3.30 | 兼容 map 类型的 get_field_value |
+| v0.3.29 | 依赖版本更改 |
+| v0.3.28 | str 支持，语义化搜索/向量搜索 |
+| v0.3.27 | 支持 dict 类型过滤 |
+| v0.3.26 | 权限配置缺失时提醒 |
+| v0.3.25 | query 验证数组逻辑更改 |
+| v0.3.24 | 权限验证绑定到关系的关系资源 |
+| v0.3.23 | Filter 类增加 get_field_value 方法 |
+| v0.3.22 | 判断接口是否有权限方法更改 |
+| v0.3.21 | 验证关系权限前判断关系是否存在 |
+| v0.3.20 | 更改 url 参数解析，使用 urllib.parse |
+| v0.3.19 | route 命唯一名 |
+| v0.3.0 | 调整 fastapi==0.92.0 |

socar_api-0.6.0/README.md

@@ -0,0 +1,151 @@
+# api_frame
+
+基于 FastAPI + JSON:API 规范的 RESTful 接口框架。
+
+[![version](https://img.shields.io/badge/version-0.6.0-blue.svg)](https://gitee.com/socar/api_frame)
+
+## 简介
+
+api_frame 提供了从资源声明 → 路由生成 → 请求处理 → 响应序列化的完整链路，让开发者**专注业务逻辑**，无需重复实现接口规范。
+
+框架提供两种资源基类：
+- **`BaseResource`** — 完整基类，支持 `connect_data()` session 管理和子资源嵌套
+- **`Resource`**（推荐） — 简化基类，内置 JSON:API 序列化管线，可直接访问 `self.db`
+
+```python
+from api_frame import Resource, SchemaBase, Field, Relationship
+
+class ArticleModel(SchemaBase):
+    title: str = Field(None)
+    content: str = Field(None)
+    author_id: int = Field(None, isrel=True)
+
+class Article(Resource):
+    model = ArticleModel
+
+    class Meta:
+        link = '/articles'
+        type_ = 'articles'
+
+    class RelResources:
+        author = Relationship(
+            rel_resource='Author',
+            mapping_field='author_id',
+            has_api=False,
+        )
+
+    async def get_many(self):
+        return self.db.query(ArticleModel).all()
+
+    async def post(self):
+        body = self.parse_body()
+        obj = ArticleModel(**body.model_dump())
+        self.db.add(obj)
+        self.db.commit()
+        return self.model.model_validate(obj)
+```
+
+一行 `Article.register_routes(app)` 即生成完整 JSON:API 接口。
+
+## 核心特性
+
+- **JSON:API 规范** — 请求/响应格式、资源关系、稀疏字段、include 复合文档、分页
+- **资源路由** — 类声明式路由，自动生成标准 CRUD 端点
+- **关系管理** — 一对一/一对多关系，include 深层级联（最多支持 3 层）
+- **权限系统** — 基于 scope 的 OAuth2 认证，API + 关系双层权限；支持 `@scope` 声明式配置
+- **原子操作** — JSON:API Atomic 扩展支持，批量操作 + 事务回滚
+- **文件上传/下载** — 增强的 `UploadFileResource` / `DownloadFileResource` 基类，文件类型验证、关系校验、可替换存储后端
+- **响应缓存** — `@cached()` 装饰器一行启用接口缓存，Cache-Aside 模式，可替换后端
+- **筛选过滤** — Deep Object 格式，40+ 操作符覆盖字符串/数值/列表/时间/布尔
+- **自动模型** — 根据资源自动生成请求/响应模型
+- **资源版本** — 内建 API 版本管理
+- **自动文档** — 与 FastAPI OpenAPI 集成
+
+## 安装
+
+> **要求**: Python 3.12+
+
+```bash
+pip install git+https://gitee.com/socar/api_frame
+```
+
+## 快速开始
+
+```python
+from fastapi import FastAPI
+from api_frame import BaseResource, SchemaBase, Field
+from api_frame.util import register_jsonapi_exception_handlers
+
+
+class BookModel(SchemaBase):
+    id: str = Field(None)
+    title: str = Field(None)
+    author: str = Field(None)
+
+
+class Book(BaseResource):
+    model = BookModel
+    methods = {'GET', 'GETS', 'POST', 'PATCH', 'DELETE'}
+
+    class Meta:
+        link = '/books'
+        type_ = 'books'
+
+
+app = FastAPI()
+register_jsonapi_exception_handlers(app)
+Book.register_routes(app)
+```
+
+启动后自动生成：
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| `GET` | `/books` | 资源列表 |
+| `GET` | `/books/{id}` | 单个资源 |
+| `POST` | `/books` | 新增资源 |
+| `PATCH` | `/books/{id}` | 更新资源 |
+| `DELETE` | `/books/{id}` | 删除资源 |
+| `POST` | `/atomic` | 原子操作（`register_routes()` 自动注册） |
+
+## 文档
+
+- [框架概述 & 核心概念](docs/index.md)
+- [快速开始指南](docs/guide.md)
+- [API 参考](docs/api.md)
+- [原子操作设计文档](docs/atomic.md)
+
+## 安装指定版本
+
+```bash
+pip install git+https://gitee.com/socar/api_frame.git@v0.6.0
+```
+
+## 版本历史
+
+| 版本 | 说明 |
+|------|------|
+| v0.6.0 | 声明式 scope 配置 (`@scope`)、增强文件上传/下载基类 (`filebase.py`)、统一缓存装饰器 (`@cached`)、SecurityConfig strict 模式。405 tests |
+| v0.5.11 | `create_filter_model` 处理 `typing.Union`（`Optional[X]`）；`page[limit]`/`page[offset]` 解析后转为 `int`。330 tests |
+| v0.5.10 | `relapi=False` 时不生成 relationship links；`has_self_link` 控制 `data.links.self`；顶层 `links.self` 保留原始 request URL 的全部 query params；分页导航 `first/last/prev/next` 保留 `filter/sort/include` 等非分页参数；`get_host()` 不再硬编码 HTTPS，保留实际请求协议。325 tests |
+| v0.5.9 | UploadFileBaseResource `examples` list 格式 + `e.raw_errors→e.errors()`（Pydantic v2 兼容）；include 兄弟节点 `asyncio.gather` 并行；Schema cache double-lookup 优化（13 处）；`list[tuple]→Union` 修复（Pydantic v2 homogeneous list 退化）；`_build_response` / `_jsonapi` 单资源 `links.self` 含 ID（含 BaseResource 路径修复）；NumberFilter/FloatFilter 增加 `aeq`；306 tests |
+| v0.5.8 | JSON:API v1.1 合规全闭环（POST Location 头、PATCH body.id 409 校验、422 JSON Pointer `source.pointer`、顶层 `links.self` 含 ID、include 保留连字符、查询参数命名约定、分页 `links.first/last/prev/next` URL）；`lid` 支持（ResourceIdentifier/RelationshipModel/ApiDataModelRequest）；filter NumberFilter/FloatFilter 增加 `aeq` 操作符；query.py dict 类型检测兼容 Python 3.12（`__origin__ is dict`）；`list[tuple(...)]` → Union（Pydantic v2 退化为 homogeneous list 修复）；exception.py 空 parts JSON Pointer 边界保护；`_build_response` 单资源 `links.self` 正确提取 ID；303 tests |
+| v0.5.7 | resource.py _jsonapi 新增 `many` 参数，空结果根据 many 返回 `[]` 或 `null`；handlers.py make_related_handler 对 to-one 404 自动转换为 `data: null`（修复 `/models/{id}/measure` 等 related 端点 500）；292 tests |
+| v0.5.6 | filter.py: UnionType (`int\|None`) + GenericAlias (`list[str]`) 支持；serializer.py: None to-one 关系产出 null 标识符；query.py: Filters/ArgsModel 的 get_field_value/get_filter/pop_and_filter 递归遍历 FilterOr；移除根目录残留 `__init__.py`；292 tests |
+| v0.5.4 | JSON:API v1.1 合规收紧（ErrorModel.status str 强制 + field_validator 自动 int→str；ResourceIdentifier.id/type 必填不可空；ErrorResponse model_dump 默认 exclude_none）；RefRes.id 统一 str；status 校验增加 bool 拒绝 + HTTP 100-599 区间；ResourceIdentifier validator mode=before + whitespace strip 自动规范化；新增边界测试覆盖空白 id、status 区间边界；292 tests |
+| v0.5.3 | JSON:API v1.1 合规改进（ErrorModel/ErrorResponse/LinksSelfModel 扩展 v1.1 字段）；related_cond/serializer request 传递 bug 修复；ApiDataModelResponse.id 类型收紧；get_field_value 类型注解修正 + ArgsModel 多值一致性；jsonapi.version → 1.1；LinksRelatedModel 补全 href/meta；OpenAPI summary 自然中文描述 + 资源类型前缀；清除废弃注释代码和构建残留；415/406 Content-Type/Accept 校验中间件 JSONAPIContentNegotiationMiddleware；移除废弃 Pydantic v1 兼容层（Meta.dict → model_dump、__fields__ → model_fields）；RdentifierMeta → IdentifierMeta 正名；过期 warning 升级为 error；StrEnum / PEP 695 语法迁移；examples/ 全面清理；filterwarnings 移除；mypy 严格模式；requires-python ≥3.12；新增 31 合规补集测试（共 289 pass） |
+| v0.5.0 | Pydantic v2 原生迁移；resource.py 拆分为 router/serializer/handlers/atomic 四模块；新增简化基类 Resource；Python 3.10+ 语法（`int | str` 替代 `Union`）；FastAPI 0.136；移除 clean.py、build/；OpenAPI summary 优化 |
+| v0.4.0 | 原子操作 Atomic 支持、权限三态模型（未配 scope = 放行）、docs 文档 |
+| v0.3.30 | 兼容 map 类型的 get_field_value |
+| v0.3.29 | 依赖版本更改 |
+| v0.3.28 | str 支持，语义化搜索/向量搜索 |
+| v0.3.27 | 支持 dict 类型过滤 |
+| v0.3.26 | 权限配置缺失时提醒 |
+| v0.3.25 | query 验证数组逻辑更改 |
+| v0.3.24 | 权限验证绑定到关系的关系资源 |
+| v0.3.23 | Filter 类增加 get_field_value 方法 |
+| v0.3.22 | 判断接口是否有权限方法更改 |
+| v0.3.21 | 验证关系权限前判断关系是否存在 |
+| v0.3.20 | 更改 url 参数解析，使用 urllib.parse |
+| v0.3.19 | route 命唯一名 |
+| v0.3.0 | 调整 fastapi==0.92.0 |

socar_api-0.6.0/pyproject.toml

@@ -0,0 +1,86 @@
+[build-system]
+requires = ["setuptools>=82.0", "wheel>=0.47"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "socar-api"
+version = "0.6.0"
+description = "基于 FastAPI + JSON:API 规范的 RESTful 接口框架"
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+authors = [
+    { name = "so.car", email = "socar@so.car" },
+]
+
+dependencies = [
+    "fastapi>=0.136.3",
+    "pydantic>=2.13.4",
+    "jquery-unparam>=2.0.0",
+    "pyyaml>=6.0.3",
+    "treelib>=1.8.0",
+    "bitarray>=3.8.1",
+    "python-multipart>=0.0.32",
+    "python-dateutil>=2.9.0.post0",
+    "typing-extensions>=4.15.0",
+]
+
+[tool.setuptools.packages.find]
+include = ["api_frame*", "examples*"]
+where = ["src"]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=9.0.3",
+    "pytest-asyncio>=1.4.0",
+    "httpx>=0.28.1",
+    "pytest-cov>=7.1.0",
+    "ruff>=0.15.16",
+    "mypy>=2.1.0",
+    "pre-commit>=4.6.0",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+
+[tool.ruff]
+target-version = "py312"
+line-length = 120
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "N", "UP"]
+
+[tool.ruff.lint.per-file-ignores]
+"src/api_frame/schema.py" = ["E501"]
+"src/api_frame/*" = ["E402"]
+"examples/*" = ["E501"]
+"tests/test_serializer.py" = ["E402"]
+[tool.mypy]
+python_version = "3.12"
+ignore_missing_imports = true
+disallow_untyped_defs = true
+no_implicit_optional = true
+
+[[tool.mypy.overrides]]
+module = [
+    "api_frame.schema",
+    "api_frame.filter",
+    "api_frame.query",
+    "api_frame.jsonapi",
+    "api_frame.resource",
+    "api_frame.serializer",
+    "api_frame.handlers",
+    "api_frame.field",
+    "api_frame.auth",
+    "api_frame.exception",
+    "api_frame.atomic",
+    "api_frame.router",
+    "api_frame.url_parse",
+    "api_frame.meta",
+    "api_frame.util",
+    "api_frame.cache",
+    "api_frame.filebase",
+    "api_frame.scope",
+]
+ignore_errors = true

socar_api-0.6.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

socar_api-0.6.0/src/api_frame/__init__.py

@@ -0,0 +1,16 @@
+__version__ = "0.6.0"
+
+from api_frame.auth import Auth  # noqa: F401
+from api_frame.cache import MemoryBackend, cached, set_default_backend, set_version_hook  # noqa: F401
+from api_frame.exception import (  # noqa: F401
+    AuthError,
+    JsonapiException,
+    QureyError,
+    ResourceDuplicate,
+    ResourceNotFound,
+)
+from api_frame.filebase import DownloadFileResource, UploadFileResource  # noqa: F401
+from api_frame.query import ArgParse, Filter, FilterAnd, FilterOr  # noqa: F401
+from api_frame.resource import BaseResource, Resource, UploadFileBaseResource  # noqa: F401
+from api_frame.schema import Relationship, SchemaBase, field_mapping  # noqa: F401
+from api_frame.scope import scope  # noqa: F401

socar_api-0.6.0/src/api_frame/atomic.py

@@ -0,0 +1,212 @@
+#!/usr/bin/env python3
+"""Atomic operations module extracted from resource.py.
+
+Provides AtomicOperation dataclass and AtomicExecutor class for
+processing JSON:API atomic operations without mutating the request.
+"""
+
+import logging
+from dataclasses import dataclass
+from typing import Any, Literal
+
+logger = logging.getLogger(__name__)
+
+from fastapi import Request
+
+from api_frame.exception import AuthError, JsonapiException, serialize_error
+from api_frame.meta import type_registered_resources
+
+
+@dataclass
+class AtomicOperation:
+    """Represents a single atomic operation.
+
+    Attributes:
+        op: The operation type ('add', 'update', 'remove')
+        target_cls: The target resource class
+        data: Operation data dict (from 'data' field)
+        ref_id: Optional reference id (for 'update' and 'remove')
+    """
+
+    op: Literal["add", "update", "remove"]
+    target_cls: type[Any]
+    data: dict
+    ref_id: str | None = None
+
+
+class AtomicExecutor:
+    """Executes JSON:API atomic operations.
+
+    Processes a list of atomic operations by creating resource instances
+    directly and calling their post/patch/delete methods, without
+    mutating request.scope or request._json on the original request.
+    """
+
+    def __init__(self, request: Request):
+        self.request = request
+
+    async def run(self, operations: list[dict]) -> dict:
+        """Execute a list of atomic operations.
+
+        Args:
+            operations: List of operation dicts from 'atomic:operations'
+
+        Returns:
+            dict with 'atomic:results' key containing operation results
+
+        Raises:
+            JsonapiException: On validation errors
+            AuthError: On permission errors
+        """
+        if not operations:
+            raise JsonapiException(status_code=400, detail="atomic:operations 不能为空")
+
+        # 阶段1：解析并验证所有操作
+        resolved = await self._parse_operations(operations)
+
+        # 阶段2：在共享事务中执行所有操作
+        return await self._execute_operations(resolved)
+
+    async def _parse_operations(self, operations: list[dict]) -> list[tuple]:
+        """Parse and validate all operations.
+
+        Returns list of (op, target_cls, op_data, ref_id) tuples.
+        """
+        op_to_method = {"add": "POST", "update": "PATCH", "remove": "DELETE"}
+        resolved = []
+
+        for op_data in operations:
+            op = op_data.get("op")
+            if op not in ("add", "update", "remove"):
+                raise JsonapiException(status_code=400, detail=f"不支持的操作符: {op}")
+
+            if op == "add":
+                target_type = op_data.get("data", {}).get("type")
+                ref_id = None
+            else:
+                ref = op_data.get("ref", {})
+                target_type = ref.get("type")
+                ref_id = ref.get("id")
+                if not ref_id:
+                    raise JsonapiException(status_code=400, detail="缺少资源 id")
+
+            if not target_type:
+                raise JsonapiException(status_code=400, detail="缺少资源类型 type")
+
+            target_cls = type_registered_resources.get(target_type)
+            if not target_cls:
+                raise JsonapiException(status_code=400, detail=f"资源类型不存在: {target_type}")
+
+            # 检查权限
+            if target_cls.Auth:
+                scope = target_cls.Auth.get_scopes(api_url=target_cls.Meta.link, method=op_to_method[op])
+                if scope is not None:
+                    has_perm = await target_cls.Auth.api_auth(api_url=target_cls.Meta.link, method=op_to_method[op])
+                    if not has_perm:
+                        raise AuthError(detail=f"没有 {op_to_method[op]} {target_type} 的权限")
+
+            resolved.append((op, target_cls, op_data, ref_id))
+
+        return resolved
+
+    async def _execute_operations(self, resolved: list[tuple]) -> dict:
+        """Execute validated operations with shared transaction management."""
+        shared_db = None
+        last_target_cls = None  # 用于异常时的错误处理回退
+        try:
+            # 获取 session 数据源
+            session_source = next((tc for _, tc, _, _ in resolved if tc.session is not None), None)
+
+            if session_source and session_source.session:
+                shared_db = session_source.session.get()
+                try:
+                    shared_db.rollback()
+                except BaseException:
+                    pass
+
+            results = []
+            for op, target_cls, op_data, ref_id in resolved:
+                last_target_cls = target_cls
+                result = await self._execute_single(op, target_cls, op_data, ref_id, shared_db)
+                results.append(
+                    {
+                        "data": {
+                            "type": target_cls.Meta.type_,
+                            "id": result.id if result and hasattr(result, "id") else None,
+                        }
+                    }
+                )
+
+            if shared_db:
+                shared_db.commit()
+
+            return {"atomic:results": results}
+
+        except BaseException as e:
+            if shared_db:
+                shared_db.rollback()
+            if last_target_cls is not None:
+                return await last_target_cls.handle_error(request=self.request, exc=e)
+            return await self._fallback_error(e)
+        finally:
+            if shared_db:
+                shared_db.close()
+
+    async def _execute_single(self, op: str, target_cls: type, op_data: dict, ref_id: str | None, shared_db):
+        """Execute a single atomic operation.
+
+        Creates a resource instance and calls the appropriate handler,
+        without mutating request.scope or request._json.
+        """
+        if op == "add":
+            body = op_data.get("data", {}).copy()
+            resource = target_cls(request=self.request, request_context={"request_body": {"data": body}})
+            # 标记为新增操作
+            resource._atomic_op = "add"
+            resource._atomic_body = body
+            if shared_db:
+                resource.db = shared_db
+            result = await resource.post()
+            if shared_db and resource.db is not shared_db:
+                logger.warning(
+                    "原子操作: %s.post() 内部调用了 connect_data，已自动恢复共享事务", target_cls.Meta.type_
+                )
+                resource.db = shared_db
+
+        elif op == "update":
+            body = op_data.get("data", {}).copy()
+            body["id"] = ref_id
+            body.setdefault("type", target_cls.Meta.type_)
+            resource = target_cls(request=self.request, request_context={"request_body": {"data": body}})
+            # 标记为更新操作
+            resource._atomic_op = "update"
+            resource._atomic_body = body
+            resource._atomic_id = ref_id
+            if shared_db:
+                resource.db = shared_db
+            result = await resource.patch()
+            if shared_db and resource.db is not shared_db:
+                logger.warning(
+                    "原子操作: %s.patch() 内部调用了 connect_data，已自动恢复共享事务", target_cls.Meta.type_
+                )
+                resource.db = shared_db
+
+        else:  # remove
+            resource = target_cls(request=self.request)
+            resource._atomic_op = "remove"
+            resource._atomic_id = ref_id
+            if shared_db:
+                resource.db = shared_db
+            result = await resource.delete()
+            if shared_db and resource.db is not shared_db:
+                logger.warning(
+                    "原子操作: %s.delete() 内部调用了 connect_data，已自动恢复共享事务", target_cls.Meta.type_
+                )
+                resource.db = shared_db
+
+        return result
+
+    async def _fallback_error(self, exc: BaseException) -> dict:
+        """Fallback error handler when target_cls is not available."""
+
+        return serialize_error(request=self.request, exc=exc)