fastapi-augment 0.1.2__tar.gz → 0.1.4__tar.gz

{fastapi_augment-0.1.2 → fastapi_augment-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi-augment
-Version: 0.1.2
+Version: 0.1.4
 Summary: FastAPI 通用代码工具包，跨项目复用
 Author-email: zarkhan <hanguangzheng@qq.com>
 License-Expression: MIT
@@ -45,10 +45,11 @@ Requires-Dist: fastapi-augment[config,orjson,sqlalchemy,uvicorn]; extra == "stan
 - **生命周期管理** — 多注册表、优先级、超时控制、异常策略的启动/关闭钩子
 - **读写分离** — 单库 / 主从 / 集群拓扑的异步引擎管理，线程安全的 Session 自动路由
 - **泛型仓储** — 类型安全的异步 Repository，支持直接实例化与子类继承两种方式
+- **查询解析器** — REST 风格 query string 转 SQLAlchemy 表达式，支持 FIQL 条件、关键字搜索、排序
 - **可组合 Mixin** — 时间戳、审计、软删除等列混入，自由组合
 - **统一响应** — 全局 `APIResponse` 格式，自动追踪 `request_id`
 - **HTTP 异常** — 完整的 4xx 异常子类，内置默认文案
-- **OpenAPI 优化** — 自动清理 422 响应、可选 Bearer 认证
+- **OpenAPI 优化** — 自动清理 422 响应与验证错误模型
 - **日志管理** — request_id 自动注入、uvicorn 接管、多进程安全轮转、幂等初始化、一键配置
 - **健康检查** — 可扩展的检查器模式，内置应用状态与数据库连通性检查，一行开关
 - **配置管理** — 基于 pydantic-settings，支持 `.env` 文件、环境变量前缀、嵌套配置
@@ -130,7 +131,7 @@ app = create_app(
 | 生命周期 | 接入 `fastapi_lifespan`，合并用户注册表与 `core_registry`  |
 | 中间件   | 自动添加 `RequestIdMiddleware`，可选 CORS                  |
 | 路由     | 支持 `APIRouter` 列表或 `(router, kwargs)` 元组            |
-| OpenAPI  | 自动清理 422 响应、可选 Bearer 认证                        |
+| OpenAPI  | 自动清理 422 响应与验证错误模型                            |
 | 数据库   | 可选挂载 `EngineManager` / `SessionFactory` 到 `app.state` |
 | 健康检查 | `health_check=True` 一键启用 `/health` 端点                |
 
@@ -147,7 +148,6 @@ app = create_app(
     title='My Service',
     registries=registry,             # 单个或列表均可
     cors_allow_origins=['*'],
-    openapi_enable_bearer_auth=True,
     health_check=True,          # 启用健康检查
 )
 ```
@@ -260,10 +260,12 @@ from fastapi_augment.db.sqlalchemy import RepositoryBase
 # 方式 1：直接实例化 — 显式传入模型类
 user_repo = RepositoryBase(User)
 
+
 # 方式 2：子类继承 — 通过泛型参数绑定模型，可扩展自定义方法
 class UserRepo(RepositoryBase[User]):
     async def find_by_email(self, session, email: str) -> User | None:
-        return await self.get_one(session, email=email)
+        return await self.get_first(session, email=email)
+
 
 user_repo = UserRepo()  # 无需再传 User
 ```
@@ -279,7 +281,8 @@ async with sessions.transaction() as session:
 # Read（实例方法）
 async with sessions.read_session() as session:
     user = await user_repo.get(session, id_='01HXK...')
-    user = await user_repo.get_one(session, name='alice')
+    user = await user_repo.get_first(session, name='alice')        # 取第一条，无匹配返回 None
+    user = await user_repo.get_unique(session, email='a@b.com')   # 精确唯一，多条匹配抛 MultipleResultsFound
     users = await user_repo.list(session, role='admin', order_by=['-created_at'], limit=10)
     total = await user_repo.count(session, is_active=True)
     has_admin = await user_repo.exists(session, role='admin')
@@ -319,6 +322,92 @@ await user_repo.list(session, expressions=(User.age > 18,))
 await user_repo.list(session, order_by=['-created_at', 'name'])
 ```
 
+### 查询解析器 — `query_parser`
+
+将 REST 风格的 query string 转为 SQLAlchemy `ColumnElement` 条件表达式，可直接传入 `RepositoryBase` 的 `expressions` / `order_by` 参数。
+
+#### where 组合条件（FIQL 风格）
+
+```
+where = and_group ("," and_group)*        , 表示 OR
+and_group = unit (";" unit)*              ; 表示 AND
+unit = "(" where ")" | condition
+condition = field OP value
+```
+
+**支持的操作符：**
+
+| 语法             | 含义                 | 示例                      |
+| ---------------- | -------------------- | ------------------------- |
+| `field==value`   | 等于                 | `status==1`               |
+| `field!=value`   | 不等                 | `status!=0`               |
+| `field~=value`   | 模糊包含 (ILIKE)     | `name~=张`                |
+| `field>value`    | 大于                 | `age>18`                  |
+| `field>=value`   | 大于等于             | `age>=18`                 |
+| `field<value`    | 小于                 | `age<60`                  |
+| `field<=value`   | 小于等于             | `age<=60`                 |
+| `field~start~end`| 区间 (BETWEEN)       | `age~18~60`               |
+
+```python
+from fastapi_augment.db.sqlalchemy import parse_where
+
+# 昵称含张 且 状态非禁用
+expr = parse_where('nickname~=张;status!=0', User)
+
+# 括号内 OR，与区间 AND
+expr = parse_where('(nickname~=张,username~=王);age~20~30', User)
+```
+
+#### lookup 精确匹配
+
+```python
+from fastapi_augment.db.sqlalchemy import parse_lookup
+
+# 单字段精确匹配
+expr = parse_lookup('phone==13800138000', User, fields={'phone', 'email'})
+
+# 多字段 AND（; 分隔）
+expr = parse_lookup('phone==138;status==1', User, fields={'phone', 'status'})
+```
+
+#### 关键字搜索
+
+```python
+from fastapi_augment.db.sqlalchemy import parse_keyword
+
+# 多字段 OR 模糊搜索
+expr = parse_keyword('admin', 'username,email,nickname', User)
+```
+
+#### 排序
+
+```python
+from fastapi_augment.db.sqlalchemy import parse_sort
+
+# - 前缀表示降序，无前缀为升序
+order_by = parse_sort('-created_at,nickname', User)
+```
+
+#### 一键组合 — `build_query_expressions`
+
+```python
+from fastapi_augment.db.sqlalchemy import build_query_expressions
+
+expressions, order_by = build_query_expressions(
+    User,
+    where='status!=0;age>=18',
+    q='admin',
+    q_field='username,nickname',
+    sort='-created_at',
+)
+
+# 直接传给 paginate / list
+result = await user_repo.paginate(
+    session, page=1, size=10,
+    expressions=expressions, order_by=order_by,
+)
+```
+
 ### 数据库迁移 CLI — `fastapi-augment-migrate`
 
 内置 Alembic 迁移工具，提供 `init` / `generate` / `upgrade` 三个子命令，开箱即用。
@@ -508,12 +597,12 @@ raise BadRequestError(detail='用户名不能为空')
 raise TooManyRequestsError(retry_after=60)
 ```
 
-### 日志管理 — `log`
+### 日志管理 — `logger`
 
 导入即生效：自动注入 `request_id` 到每条日志、接管 uvicorn/fastapi 日志输出。
 
 ```python
-from fastapi_augment.log import setup_logger, set_log_level
+from fastapi_augment.logger import setup_logger, set_log_level
 
 # 一键配置：控制台 + 按天轮转文件日志
 setup_logger(log_dir='./logs', rotation='day', backup_count=30)
@@ -602,26 +691,30 @@ app.include_router(create_health_router(
 
 ### 配置管理 — `config`
 
-基于 `pydantic-settings`，通过 `from_env()` 直接传参，无需手动导入 `SettingsConfigDict`：
+基于 `pydantic-settings`，支持多种配置来源（环境变量、.env、JSON、YAML、TOML），通过不同类方法加载：
 
 ```python
-from fastapi_augment.config import EnvSettings
+from fastapi_augment.config import AugmentBaseSettings
 
-class Settings(EnvSettings):
+class Settings(AugmentBaseSettings):
     database_url: str
     redis_url: str = ''
     debug: bool = False
     secret_key: str = 'change-me'
 
-# 直接传入 .env 路径、前缀等
-settings = Settings.from_env(
-    env_file='config/.env',
-    env_prefix='APP_',
-    env_nested_delimiter='__',
-)
+# 从环境变量加载
+cfg = Settings.from_env(env_prefix='APP_', env_nested_delimiter='__')
+
+# 从 .env 文件加载
+cfg = Settings.from_dotenv('.env', env_prefix='APP_')
+
+# 从 JSON / YAML / TOML 文件加载
+cfg = Settings.from_json('config.json')
+cfg = Settings.from_yaml('config.yaml')
+cfg = Settings.from_toml('config.toml')
 ```
 
-支持 `SettingsConfigDict` 的所有参数（`env_file`、`env_prefix`、`secrets_dir`、`yaml_file` 等），
+支持 `SettingsConfigDict` 的所有参数（`env_prefix`、`secrets_dir`、`yaml_file` 等），
 与模型字段值自动区分，无需关心分类。
 
 ### 中间件 — `middlewares`
@@ -647,13 +740,15 @@ fastapi_augment/
 │   └── utils/
 │       └── strings.py        # 字符串工具 / JSON 序列化
 ├── config/
-│   └── settings.py           # EnvSettings 配置管理
+│   ├── base_settings.py       # AugmentBaseSettings 配置管理
+│   └── database_settings.py   # DatabaseSettings 数据库配置
 ├── db/
 │   └── sqlalchemy/
 │       ├── engine.py         # EngineManager / NodeConfig / ClusterTopology
 │       ├── session.py        # SessionFactory（读写分离）
 │       ├── model_base.py     # ModelBase（ULID 主键）
 │       ├── repository_base.py # RepositoryBase（泛型仓储 + paginate）
+│       ├── query_parser.py    # 查询解析器（where / lookup / keyword / sort）
 │       ├── migrate.py        # 数据库迁移 CLI
 │       ├── migrations/       # Alembic 迁移环境（env.py / script.py.mako）
 │       └── mixins/           # Timestamp / Audit / SoftDelete
@@ -661,11 +756,11 @@ fastapi_augment/
 │   ├── checker.py            # BaseChecker / CheckResult / HealthResponse
 │   ├── checkers.py           # AppChecker / DatabaseChecker
 │   └── router.py             # create_health_router()
-├── log/
-│   ├── factory.py            # request_id 注入工厂
+├── logger/
+│   ├── record_factory.py     # request_id 注入工厂
 │   ├── filters.py            # UvicornNameRewriteFilter
 │   ├── handlers.py           # 多进程安全轮转处理器
-│   └── config.py             # setup_logger / set_log_level / set_log_format
+│   └── setup.py              # setup_logger / set_log_level / set_log_format
 ├── middlewares/
 │   ├── base.py               # BaseASGIMiddleware
 │   └── request_id.py         # RequestId 中间件

{fastapi_augment-0.1.2 → fastapi_augment-0.1.4}/README.md

@@ -8,10 +8,11 @@
 - **生命周期管理** — 多注册表、优先级、超时控制、异常策略的启动/关闭钩子
 - **读写分离** — 单库 / 主从 / 集群拓扑的异步引擎管理，线程安全的 Session 自动路由
 - **泛型仓储** — 类型安全的异步 Repository，支持直接实例化与子类继承两种方式
+- **查询解析器** — REST 风格 query string 转 SQLAlchemy 表达式，支持 FIQL 条件、关键字搜索、排序
 - **可组合 Mixin** — 时间戳、审计、软删除等列混入，自由组合
 - **统一响应** — 全局 `APIResponse` 格式，自动追踪 `request_id`
 - **HTTP 异常** — 完整的 4xx 异常子类，内置默认文案
-- **OpenAPI 优化** — 自动清理 422 响应、可选 Bearer 认证
+- **OpenAPI 优化** — 自动清理 422 响应与验证错误模型
 - **日志管理** — request_id 自动注入、uvicorn 接管、多进程安全轮转、幂等初始化、一键配置
 - **健康检查** — 可扩展的检查器模式，内置应用状态与数据库连通性检查，一行开关
 - **配置管理** — 基于 pydantic-settings，支持 `.env` 文件、环境变量前缀、嵌套配置
@@ -93,7 +94,7 @@ app = create_app(
 | 生命周期 | 接入 `fastapi_lifespan`，合并用户注册表与 `core_registry`  |
 | 中间件   | 自动添加 `RequestIdMiddleware`，可选 CORS                  |
 | 路由     | 支持 `APIRouter` 列表或 `(router, kwargs)` 元组            |
-| OpenAPI  | 自动清理 422 响应、可选 Bearer 认证                        |
+| OpenAPI  | 自动清理 422 响应与验证错误模型                            |
 | 数据库   | 可选挂载 `EngineManager` / `SessionFactory` 到 `app.state` |
 | 健康检查 | `health_check=True` 一键启用 `/health` 端点                |
 
@@ -110,7 +111,6 @@ app = create_app(
     title='My Service',
     registries=registry,             # 单个或列表均可
     cors_allow_origins=['*'],
-    openapi_enable_bearer_auth=True,
     health_check=True,          # 启用健康检查
 )
 ```
@@ -223,10 +223,12 @@ from fastapi_augment.db.sqlalchemy import RepositoryBase
 # 方式 1：直接实例化 — 显式传入模型类
 user_repo = RepositoryBase(User)
 
+
 # 方式 2：子类继承 — 通过泛型参数绑定模型，可扩展自定义方法
 class UserRepo(RepositoryBase[User]):
     async def find_by_email(self, session, email: str) -> User | None:
-        return await self.get_one(session, email=email)
+        return await self.get_first(session, email=email)
+
 
 user_repo = UserRepo()  # 无需再传 User
 ```
@@ -242,7 +244,8 @@ async with sessions.transaction() as session:
 # Read（实例方法）
 async with sessions.read_session() as session:
     user = await user_repo.get(session, id_='01HXK...')
-    user = await user_repo.get_one(session, name='alice')
+    user = await user_repo.get_first(session, name='alice')        # 取第一条，无匹配返回 None
+    user = await user_repo.get_unique(session, email='a@b.com')   # 精确唯一，多条匹配抛 MultipleResultsFound
     users = await user_repo.list(session, role='admin', order_by=['-created_at'], limit=10)
     total = await user_repo.count(session, is_active=True)
     has_admin = await user_repo.exists(session, role='admin')
@@ -282,6 +285,92 @@ await user_repo.list(session, expressions=(User.age > 18,))
 await user_repo.list(session, order_by=['-created_at', 'name'])
 ```
 
+### 查询解析器 — `query_parser`
+
+将 REST 风格的 query string 转为 SQLAlchemy `ColumnElement` 条件表达式，可直接传入 `RepositoryBase` 的 `expressions` / `order_by` 参数。
+
+#### where 组合条件（FIQL 风格）
+
+```
+where = and_group ("," and_group)*        , 表示 OR
+and_group = unit (";" unit)*              ; 表示 AND
+unit = "(" where ")" | condition
+condition = field OP value
+```
+
+**支持的操作符：**
+
+| 语法             | 含义                 | 示例                      |
+| ---------------- | -------------------- | ------------------------- |
+| `field==value`   | 等于                 | `status==1`               |
+| `field!=value`   | 不等                 | `status!=0`               |
+| `field~=value`   | 模糊包含 (ILIKE)     | `name~=张`                |
+| `field>value`    | 大于                 | `age>18`                  |
+| `field>=value`   | 大于等于             | `age>=18`                 |
+| `field<value`    | 小于                 | `age<60`                  |
+| `field<=value`   | 小于等于             | `age<=60`                 |
+| `field~start~end`| 区间 (BETWEEN)       | `age~18~60`               |
+
+```python
+from fastapi_augment.db.sqlalchemy import parse_where
+
+# 昵称含张 且 状态非禁用
+expr = parse_where('nickname~=张;status!=0', User)
+
+# 括号内 OR，与区间 AND
+expr = parse_where('(nickname~=张,username~=王);age~20~30', User)
+```
+
+#### lookup 精确匹配
+
+```python
+from fastapi_augment.db.sqlalchemy import parse_lookup
+
+# 单字段精确匹配
+expr = parse_lookup('phone==13800138000', User, fields={'phone', 'email'})
+
+# 多字段 AND（; 分隔）
+expr = parse_lookup('phone==138;status==1', User, fields={'phone', 'status'})
+```
+
+#### 关键字搜索
+
+```python
+from fastapi_augment.db.sqlalchemy import parse_keyword
+
+# 多字段 OR 模糊搜索
+expr = parse_keyword('admin', 'username,email,nickname', User)
+```
+
+#### 排序
+
+```python
+from fastapi_augment.db.sqlalchemy import parse_sort
+
+# - 前缀表示降序，无前缀为升序
+order_by = parse_sort('-created_at,nickname', User)
+```
+
+#### 一键组合 — `build_query_expressions`
+
+```python
+from fastapi_augment.db.sqlalchemy import build_query_expressions
+
+expressions, order_by = build_query_expressions(
+    User,
+    where='status!=0;age>=18',
+    q='admin',
+    q_field='username,nickname',
+    sort='-created_at',
+)
+
+# 直接传给 paginate / list
+result = await user_repo.paginate(
+    session, page=1, size=10,
+    expressions=expressions, order_by=order_by,
+)
+```
+
 ### 数据库迁移 CLI — `fastapi-augment-migrate`
 
 内置 Alembic 迁移工具，提供 `init` / `generate` / `upgrade` 三个子命令，开箱即用。
@@ -471,12 +560,12 @@ raise BadRequestError(detail='用户名不能为空')
 raise TooManyRequestsError(retry_after=60)
 ```
 
-### 日志管理 — `log`
+### 日志管理 — `logger`
 
 导入即生效：自动注入 `request_id` 到每条日志、接管 uvicorn/fastapi 日志输出。
 
 ```python
-from fastapi_augment.log import setup_logger, set_log_level
+from fastapi_augment.logger import setup_logger, set_log_level
 
 # 一键配置：控制台 + 按天轮转文件日志
 setup_logger(log_dir='./logs', rotation='day', backup_count=30)
@@ -565,26 +654,30 @@ app.include_router(create_health_router(
 
 ### 配置管理 — `config`
 
-基于 `pydantic-settings`，通过 `from_env()` 直接传参，无需手动导入 `SettingsConfigDict`：
+基于 `pydantic-settings`，支持多种配置来源（环境变量、.env、JSON、YAML、TOML），通过不同类方法加载：
 
 ```python
-from fastapi_augment.config import EnvSettings
+from fastapi_augment.config import AugmentBaseSettings
 
-class Settings(EnvSettings):
+class Settings(AugmentBaseSettings):
     database_url: str
     redis_url: str = ''
     debug: bool = False
     secret_key: str = 'change-me'
 
-# 直接传入 .env 路径、前缀等
-settings = Settings.from_env(
-    env_file='config/.env',
-    env_prefix='APP_',
-    env_nested_delimiter='__',
-)
+# 从环境变量加载
+cfg = Settings.from_env(env_prefix='APP_', env_nested_delimiter='__')
+
+# 从 .env 文件加载
+cfg = Settings.from_dotenv('.env', env_prefix='APP_')
+
+# 从 JSON / YAML / TOML 文件加载
+cfg = Settings.from_json('config.json')
+cfg = Settings.from_yaml('config.yaml')
+cfg = Settings.from_toml('config.toml')
 ```
 
-支持 `SettingsConfigDict` 的所有参数（`env_file`、`env_prefix`、`secrets_dir`、`yaml_file` 等），
+支持 `SettingsConfigDict` 的所有参数（`env_prefix`、`secrets_dir`、`yaml_file` 等），
 与模型字段值自动区分，无需关心分类。
 
 ### 中间件 — `middlewares`
@@ -610,13 +703,15 @@ fastapi_augment/
 │   └── utils/
 │       └── strings.py        # 字符串工具 / JSON 序列化
 ├── config/
-│   └── settings.py           # EnvSettings 配置管理
+│   ├── base_settings.py       # AugmentBaseSettings 配置管理
+│   └── database_settings.py   # DatabaseSettings 数据库配置
 ├── db/
 │   └── sqlalchemy/
 │       ├── engine.py         # EngineManager / NodeConfig / ClusterTopology
 │       ├── session.py        # SessionFactory（读写分离）
 │       ├── model_base.py     # ModelBase（ULID 主键）
 │       ├── repository_base.py # RepositoryBase（泛型仓储 + paginate）
+│       ├── query_parser.py    # 查询解析器（where / lookup / keyword / sort）
 │       ├── migrate.py        # 数据库迁移 CLI
 │       ├── migrations/       # Alembic 迁移环境（env.py / script.py.mako）
 │       └── mixins/           # Timestamp / Audit / SoftDelete
@@ -624,11 +719,11 @@ fastapi_augment/
 │   ├── checker.py            # BaseChecker / CheckResult / HealthResponse
 │   ├── checkers.py           # AppChecker / DatabaseChecker
 │   └── router.py             # create_health_router()
-├── log/
-│   ├── factory.py            # request_id 注入工厂
+├── logger/
+│   ├── record_factory.py     # request_id 注入工厂
 │   ├── filters.py            # UvicornNameRewriteFilter
 │   ├── handlers.py           # 多进程安全轮转处理器
-│   └── config.py             # setup_logger / set_log_level / set_log_format
+│   └── setup.py              # setup_logger / set_log_level / set_log_format
 ├── middlewares/
 │   ├── base.py               # BaseASGIMiddleware
 │   └── request_id.py         # RequestId 中间件

fastapi_augment-0.1.4/VERSION

@@ -0,0 +1 @@
+0.1.4

{fastapi_augment-0.1.2 → fastapi_augment-0.1.4}/src/fastapi_augment/common/constants.py

@@ -1,7 +1,7 @@
 """
 @Author         : hangu
 @CreateDate     : 2026/9/4
-@Description    :
+@Description    : 全局常量与统一默认错误文案
 """
 from starlette import status
 
@@ -21,6 +21,7 @@ DEFAULT_ERR_MSG: dict[int, str] = {
     status.HTTP_413_CONTENT_TOO_LARGE: 'Payload too large',
     status.HTTP_414_URI_TOO_LONG: 'URI too long',
     status.HTTP_415_UNSUPPORTED_MEDIA_TYPE: 'Unsupported media type',
+    status.HTTP_422_UNPROCESSABLE_CONTENT: 'Unprocessable entity',
     status.HTTP_423_LOCKED: 'Locked',
     status.HTTP_429_TOO_MANY_REQUESTS: 'Too many requests',
 }

{fastapi_augment-0.1.2 → fastapi_augment-0.1.4}/src/fastapi_augment/common/exception_handlers.py

@@ -27,11 +27,11 @@ async def base_http_error_handler(
         _request: Request,
         exc: BaseHttpError,
 ) -> JSONResponse:
-    """处理 BaseHttpError 及其所有子类（统一业务异常）。
+    """处理 BaseHttpError 及其所有子类（统一业务异常）
 
     将业务异常转换为统一 APIResponse 格式，
     HTTP 状态码与 exc.status_code 一致，
-    body.code 同样使用 HTTP 状态码，body.message 使用 exc.detail。
+    body.code 同样使用 HTTP 状态码，body.message 使用 exc.detail
 
     Args:
         _request: Starlette Request 对象
@@ -54,11 +54,11 @@ async def http_exception_handler(
         _request: Request,
         exc: HTTPException,
 ) -> JSONResponse:
-    """处理 Starlette/FastAPI 原生 HTTPException。
+    """处理 Starlette/FastAPI 原生 HTTPException
 
-    覆盖 FastAPI 默认处理器，将响应格式统一为 APIResponse。
+    覆盖 FastAPI 默认处理器，将响应格式统一为 APIResponse
     注意：BaseHttpError 继承自 HTTPException，但 FastAPI 会优先匹配
-    更具体的处理器（base_http_error_handler），所以此处不会拦截业务异常。
+    更具体的处理器（base_http_error_handler），所以此处不会拦截业务异常
 
     Args:
         _request: Starlette Request 对象
@@ -84,9 +84,9 @@ async def validation_exception_handler(
         _request: Request,
         exc: RequestValidationError,
 ) -> JSONResponse:
-    """处理 Pydantic 请求参数校验异常（422）。
+    """处理 Pydantic 请求参数校验异常（422）
 
-    将校验错误详情提取到 extra.errors 中，方便前端定位具体字段。
+    将校验错误详情提取到 extra.errors 中，方便前端定位具体字段
 
     Args:
         _request: Starlette Request 对象
@@ -121,10 +121,10 @@ async def general_exception_handler(
         _request: Request,
         exc: Exception,
 ) -> JSONResponse:
-    """处理所有未被捕获的异常（兜底）。
+    """处理所有未被捕获的异常（兜底）
 
     记录完整异常日志（含堆栈），但响应体只返回通用提示，
-    避免将内部实现细节（堆栈、SQL 等）暴露给客户端。
+    避免将内部实现细节（堆栈、SQL 等）暴露给客户端
 
     Args:
         _request: Starlette Request 对象
@@ -144,7 +144,7 @@ async def general_exception_handler(
 # ===================== 一键注册 =====================
 
 def register_exception_handlers(app: FastAPI) -> None:
-    """将全部统一异常处理器注册到 FastAPI 应用。
+    """将全部统一异常处理器注册到 FastAPI 应用
 
     注册后，以下异常会被转换为统一的 APIResponse 格式：
         - BaseHttpError 及子类 → 对应 HTTP 状态码

{fastapi_augment-0.1.2 → fastapi_augment-0.1.4}/src/fastapi_augment/common/exceptions.py

@@ -13,7 +13,7 @@ from .constants import DEFAULT_ERR_MSG
 
 # ===================== 通用基类：统一封装 detail + headers 逻辑 =====================
 class BaseHttpError(HTTPException):
-    """统一HTTP异常基类，所有4xx异常继承此类，原生兼容starlette.HTTPException.
+    """统一HTTP异常基类，所有4xx异常继承此类，原生兼容starlette.HTTPException
 
     子类只需声明 ``_status_code`` 类变量，无需重写 __init__::
 
@@ -38,7 +38,7 @@ class BaseHttpError(HTTPException):
             detail: str | None = None,
             headers: dict[str, Any] | None = None,
     ):
-        """初始化http业务异常.
+        """初始化http业务异常
 
         Args:
             status_code: http响应状态码，不传则读取子类的 _status_code 类变量
@@ -62,82 +62,82 @@ class BaseHttpError(HTTPException):
 # ===================== 各类4xx异常子类（极简声明，无重复__init__） =====================
 # 子类只需声明 _status_code 类变量，__init__ 由基类统一处理
 class BadRequestError(BaseHttpError):
-    """400 请求错误."""
+    """400 请求错误"""
     _status_code = status.HTTP_400_BAD_REQUEST
 
 
 class UnauthorizedError(BaseHttpError):
-    """401 未授权错误."""
+    """401 未授权错误"""
     _status_code = status.HTTP_401_UNAUTHORIZED
 
 
 class PaymentRequiredError(BaseHttpError):
-    """402 需要付费错误."""
+    """402 需要付费错误"""
     _status_code = status.HTTP_402_PAYMENT_REQUIRED
 
 
 class ForbiddenError(BaseHttpError):
-    """403 禁止访问错误."""
+    """403 禁止访问错误"""
     _status_code = status.HTTP_403_FORBIDDEN
 
 
 class NotFoundError(BaseHttpError):
-    """404 未找到资源."""
+    """404 未找到资源"""
     _status_code = status.HTTP_404_NOT_FOUND
 
 
 class MethodNotAllowedError(BaseHttpError):
-    """405 请求方法不允许."""
+    """405 请求方法不允许"""
     _status_code = status.HTTP_405_METHOD_NOT_ALLOWED
 
 
 class NotAcceptableError(BaseHttpError):
-    """406 客户端不支持返回格式."""
+    """406 客户端不支持返回格式"""
     _status_code = status.HTTP_406_NOT_ACCEPTABLE
 
 
 class RequestTimeoutError(BaseHttpError):
-    """408 请求超时."""
+    """408 请求超时"""
     _status_code = status.HTTP_408_REQUEST_TIMEOUT
 
 
 class ConflictError(BaseHttpError):
-    """409 资源冲突."""
+    """409 资源冲突"""
     _status_code = status.HTTP_409_CONFLICT
 
 
 class GoneError(BaseHttpError):
-    """410 资源已永久删除."""
+    """410 资源已永久删除"""
     _status_code = status.HTTP_410_GONE
 
 
 class PreconditionFailedError(BaseHttpError):
-    """412 前置校验失败."""
+    """412 前置校验失败"""
     _status_code = status.HTTP_412_PRECONDITION_FAILED
 
 
 class PayloadTooLargeError(BaseHttpError):
-    """413 请求体过大."""
+    """413 请求体过大"""
     _status_code = status.HTTP_413_CONTENT_TOO_LARGE
 
 
 class URITooLongError(BaseHttpError):
-    """414 URI链接过长."""
+    """414 URI链接过长"""
     _status_code = status.HTTP_414_URI_TOO_LONG
 
 
 class UnsupportedMediaTypeError(BaseHttpError):
-    """415 不支持的请求媒体类型."""
+    """415 不支持的请求媒体类型"""
     _status_code = status.HTTP_415_UNSUPPORTED_MEDIA_TYPE
 
 
 class LockedError(BaseHttpError):
-    """423 资源锁定."""
+    """423 资源锁定"""
     _status_code = status.HTTP_423_LOCKED
 
 
 class TooManyRequestsError(BaseHttpError):
-    """429 请求过于频繁（限流专用，支持retry_after快捷参数）."""
+    """429 请求过于频繁（限流专用，支持retry_after快捷参数）"""
     _status_code = status.HTTP_429_TOO_MANY_REQUESTS
 
     def __init__(