jalontsui-fastapi-kit 0.1.0__py3-none-any.whl

jalontsui_fastapi_kit/__init__.py

@@ -0,0 +1,152 @@
+"""jalontsui-common —— 项目公共基础设施包."""
+
+from jalontsui_fastapi_kit.cache import RedisClient, create_redis_client
+from jalontsui_fastapi_kit.config import BaseAppSettings
+from jalontsui_fastapi_kit.db import (
+    Base,
+    close_async_engine,
+    create_async_engine_from_url,
+    create_async_session_factory,
+    transaction,
+)
+from jalontsui_fastapi_kit.errors import (
+    BadRequestException,
+    BusinessException,
+    DatabaseConflictException,
+    DatabaseIntegrityException,
+    ErrorMessageRegistry,
+    ExceptionHandler,
+    ExceptionHandlerRegistry,
+    ExternalServiceException,
+    ForbiddenException,
+    NotFoundException,
+    UnauthorizedException,
+    ValidationException,
+    get_message,
+    set_default_locale,
+    set_request_locale,
+)
+from jalontsui_fastapi_kit.health import (
+    HealthChecker,
+    HealthCheckResponse,
+    HealthResult,
+    check_database,
+    check_redis,
+)
+from jalontsui_fastapi_kit.logging import (
+    DEFAULT_LOG_FORMAT,
+    RequestIdFilter,
+    get_request_id,
+    parse_level,
+    request_id_ctx,
+    setup_logging,
+)
+from jalontsui_fastapi_kit.middleware import (
+    REQUEST_ID_HEADER,
+    LocaleMiddleware,
+    RequestIdMiddleware,
+    setup_cors,
+)
+from jalontsui_fastapi_kit.repositories.base import BaseRepository
+from jalontsui_fastapi_kit.response import ApiResponse
+from jalontsui_fastapi_kit.schemas.common import (
+    ListResponse,
+    PageResponse,
+    ScrollPageResponse,
+)
+from jalontsui_fastapi_kit.search import (
+    ElasticsearchClient,
+    create_elasticsearch_client,
+)
+from jalontsui_fastapi_kit.services import BaseService
+from jalontsui_fastapi_kit.utils.time import utc_naive_to_local, utc_naive_to_local_str
+from jalontsui_fastapi_kit.security import (
+    captcha_image_to_base64,
+    generate_captcha_code,
+    generate_captcha_image,
+    hash_password,
+    password_needs_rehash,
+    verify_password,
+)
+from jalontsui_fastapi_kit.validation import (
+    ValidationErrorItem,
+    format_validation_errors,
+    validation_errors_to_dict,
+)
+
+__all__ = [
+    # cache
+    "RedisClient",
+    "create_redis_client",
+    # config
+    "BaseAppSettings",
+    # db
+    "Base",
+    "create_async_engine_from_url",
+    "create_async_session_factory",
+    "close_async_engine",
+    # errors
+    "ErrorMessageRegistry",
+    "get_message",
+    "set_default_locale",
+    "set_request_locale",
+    "BusinessException",
+    "NotFoundException",
+    "ValidationException",
+    "BadRequestException",
+    "UnauthorizedException",
+    "ForbiddenException",
+    "DatabaseConflictException",
+    "DatabaseIntegrityException",
+    "ExternalServiceException",
+    # handlers
+    "ExceptionHandler",
+    "ExceptionHandlerRegistry",
+    # health
+    "HealthChecker",
+    "HealthCheckResponse",
+    "HealthResult",
+    "check_database",
+    "check_redis",
+    # logging
+    "DEFAULT_LOG_FORMAT",
+    "RequestIdFilter",
+    "get_request_id",
+    "parse_level",
+    "request_id_ctx",
+    "setup_logging",
+    # middleware
+    "REQUEST_ID_HEADER",
+    "RequestIdMiddleware",
+    "LocaleMiddleware",
+    "setup_cors",
+    # repositories
+    "BaseRepository",
+    # response
+    "ApiResponse",
+    # services
+    "BaseService",
+    # transaction
+    "transaction",
+    # schemas
+    "ListResponse",
+    "PageResponse",
+    "ScrollPageResponse",
+    # search
+    "ElasticsearchClient",
+    "create_elasticsearch_client",
+    # security
+    "hash_password",
+    "verify_password",
+    "password_needs_rehash",
+    "generate_captcha_code",
+    "generate_captcha_image",
+    "captcha_image_to_base64",
+    # utils
+    "utc_naive_to_local",
+    "utc_naive_to_local_str",
+    # validation
+    "ValidationErrorItem",
+    "format_validation_errors",
+    "validation_errors_to_dict",
+]

jalontsui_fastapi_kit/cache/README.md

@@ -0,0 +1,195 @@
+# jalontsui_fastapi_kit.cache 使用指南
+
+> **适用包**：`packages/jalontsui-fastapi-kit`  
+> **作用域**：所有需要缓存/消息队列连接的 Python 服务  
+> **最后更新**：2026-07-14
+
+---
+
+## 目录
+
+1. [设计定位](#1-设计定位)
+2. [目录结构](#2-目录结构)
+3. [快速开始](#3-快速开始)
+4. [创建 Redis 客户端](#4-创建-redis-客户端)
+5. [URL 格式](#5-url-格式)
+6. [健康检查](#6-健康检查)
+7. [关闭客户端](#7-关闭客户端)
+8. [扩展其他缓存后端](#8-扩展其他缓存后端)
+9. [最佳实践](#9-最佳实践)
+
+---
+
+## 1. 设计定位
+
+`jalontsui_fastapi_kit.cache` 是项目统一的缓存/消息队列连接基础设施：
+
+- 目前提供 **Redis 异步客户端工厂**。
+- 未来可按同样模式新增 **Kafka、RabbitMQ、NATS** 等后端模块。
+- 对业务代码屏蔽连接细节，统一通过 URL 创建客户端。
+
+---
+
+## 2. 目录结构
+
+```text
+packages/jalontsui-fastapi-kit/src/jalontsui_fastapi_kit/cache/
+├── __init__.py       # 公共 API 导出
+└── redis.py          # Redis 异步客户端工厂
+```
+
+---
+
+## 3. 快速开始
+
+```python
+from jalontsui_fastapi_kit.cache import create_redis_client
+
+client = create_redis_client("redis://localhost:6379/0")
+
+await client.ping()
+await client.set("key", "value", ex=60)
+value = await client.get("key")
+
+await client.close()
+```
+
+---
+
+## 4. 创建 Redis 客户端
+
+```python
+from jalontsui_fastapi_kit.cache import create_redis_client, RedisClient
+
+client: RedisClient = create_redis_client(
+    "redis://:mypassword@localhost:6379/0",
+    decode_responses=True,                  # 默认开启，自动解码为字符串
+    socket_connect_timeout=5,
+    socket_keepalive=True,
+    health_check_interval=30,
+)
+```
+
+### 常用参数
+
+| 参数 | 说明 | 默认值 |
+|------|------|--------|
+| `url` | Redis 连接串 | 必填 |
+| `decode_responses` | 是否自动解码响应 | `True` |
+| `socket_connect_timeout` | 连接超时（秒） | 依赖 redis-py 默认 |
+| `socket_keepalive` | 是否保持长连接 | `False` |
+| `health_check_interval` | 健康检查间隔（秒） | `0` |
+
+更多参数见 [redis-py 文档](https://redis-py.readthedocs.io/en/stable/connections.html)。
+
+---
+
+## 5. URL 格式
+
+```text
+redis://[:password@]host:port/db
+```
+
+示例：
+
+```text
+redis://localhost:6379/0
+redis://:mypassword@redis.example.com:6379/0
+rediss://:mypassword@redis.example.com:6380/0   # SSL
+```
+
+在 `packages/web` 中，可通过 `settings.redis_url` 获取统一构建的连接串：
+
+```python
+from web.config import settings
+from jalontsui_fastapi_kit.cache import create_redis_client
+
+client = create_redis_client(settings.redis_url)
+```
+
+---
+
+## 6. 健康检查
+
+`jalontsui_fastapi_kit.health.check_redis` 可探测 Redis 是否可达：
+
+```python
+from jalontsui_fastapi_kit.cache import create_redis_client
+from jalontsui_fastapi_kit.health import check_redis
+
+client = create_redis_client("redis://localhost:6379/0")
+result = await check_redis(client)
+
+print(result.status)      # "ok" or "error"
+print(result.latency_ms)  # 延迟毫秒
+```
+
+在 FastAPI `/health` 端点中的典型用法：
+
+```python
+from jalontsui_fastapi_kit.cache import create_redis_client
+from jalontsui_fastapi_kit.health import HealthChecker, check_database, check_redis
+from web.config import settings
+from web.database import AsyncSessionLocal
+
+redis_client = create_redis_client(settings.redis_url)
+
+checker = HealthChecker()
+checker.register("database", lambda: check_database(async_session))
+checker.register("redis", lambda: check_redis(redis_client))
+
+response = await checker.run()
+```
+
+---
+
+## 7. 关闭客户端
+
+```python
+await client.close()
+```
+
+在 FastAPI `lifespan` 中集中管理：
+
+```python
+from contextlib import asynccontextmanager
+from fastapi import FastAPI
+from jalontsui_fastapi_kit.cache import create_redis_client
+from web.config import settings
+
+redis_client = create_redis_client(settings.redis_url)
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    yield
+    await redis_client.close()
+```
+
+---
+
+## 8. 扩展其他缓存后端
+
+未来新增缓存/消息队列后端的步骤：
+
+1. 在 `packages/jalontsui-fastapi-kit/pyproject.toml` 安装对应依赖。
+2. 在 `common/cache/` 下新增模块，例如 `common/cache/kafka.py`。
+3. 在 `common/cache/__init__.py` 中导出新的工厂函数。
+
+示例结构：
+
+```text
+common/cache/
+├── __init__.py
+├── redis.py
+└── kafka.py
+```
+
+---
+
+## 9. 最佳实践
+
+- **统一使用 URL 创建客户端**：避免在业务代码中分散拼接 host/port/password。
+- **配置集中管理**：推荐在 `Settings` 中提供 `redis_url` 属性。
+- **生命周期统一管理**：应用启动时创建，关闭时 `close()` 释放。
+- **生产环境启用 SSL**：使用 `rediss://` 协议。
+- **合理设置超时**：避免网络抖动导致请求长时间挂起。

jalontsui_fastapi_kit/cache/__init__.py

@@ -0,0 +1,14 @@
+"""通用缓存/消息队列连接工具.
+
+目前提供 Redis 异步客户端工厂，后续可按同样模式新增
+Kafka、RabbitMQ、NATS 等后端模块.
+"""
+
+from redis.asyncio import Redis as RedisClient
+
+from jalontsui_fastapi_kit.cache.redis import create_redis_client
+
+__all__ = [
+    "RedisClient",
+    "create_redis_client",
+]

jalontsui_fastapi_kit/cache/redis.py

@@ -0,0 +1,40 @@
+"""Redis 异步客户端工厂."""
+
+from __future__ import annotations
+
+from typing import Any, cast
+
+import redis.asyncio as aioredis
+
+RedisClient = aioredis.Redis
+
+
+def create_redis_client(
+    url: str,
+    *,
+    decode_responses: bool = True,
+    **kwargs: Any,
+) -> RedisClient:
+    """根据 Redis URL 创建异步客户端.
+
+    Args:
+        url: Redis 连接串，例如 redis://[:password@]host:port/db。
+        decode_responses: 是否自动将响应解码为字符串，默认开启。
+        **kwargs: 透传给 redis.asyncio.Redis.from_url 的其他参数，
+            常用于设置 socket_connect_timeout、socket_keepalive、health_check_interval 等。
+
+    Returns:
+        redis.asyncio.Redis 实例。
+
+    Example:
+        >>> client = create_redis_client("redis://localhost:6379/0")
+        >>> await client.ping()
+    """
+    return cast(
+        RedisClient,
+        aioredis.Redis.from_url(
+            url,
+            decode_responses=decode_responses,
+            **kwargs,
+        ),
+    )

jalontsui_fastapi_kit/config/README.md

@@ -0,0 +1,176 @@
+# jalontsui_fastapi_kit.config 使用指南
+
+> **适用包**：`packages/jalontsui-fastapi-kit`  
+> **作用域**：所有需要基于环境变量 / `.env` 管理配置的 Python 服务  
+> **最后更新**：2026-07-16
+
+---
+
+## 目录
+
+1. [设计定位](#1-设计定位)
+2. [目录结构](#2-目录结构)
+3. [快速开始](#3-快速开始)
+4. [配置读取优先级](#4-配置读取优先级)
+5. [继承扩展](#5-继承扩展)
+6. [环境判断属性](#6-环境判断属性)
+7. [最佳实践](#7-最佳实践)
+
+---
+
+## 1. 设计定位
+
+`jalontsui_fastapi_kit.config` 提供基于 [pydantic-settings](https://docs.pydantic.dev/latest/concepts/pydantic_settings/) 的通用配置基类 `BaseAppSettings`：
+
+- 统一配置读取入口（环境变量 + `.env` 文件）。
+- 内置应用名称、调试开关、运行环境、数据库、Redis、日志、JWT 等通用字段。
+- 各配置分块通过**多继承**扁平组合，字段统一携带分块前缀，子类继承后可直接访问。
+
+---
+
+## 2. 目录结构
+
+```text
+packages/jalontsui-fastapi-kit/src/jalontsui_fastapi_kit/config/
+├── __init__.py       # 统一组合入口 BaseAppSettings（多继承各配置分块）
+├── base.py           # 通用配置骨架 BaseAppConfig
+├── app.py            # 应用基础配置 AppConfig（app_* 字段）
+├── common.py         # 公共配置 CommonConfig（common_* 字段）
+├── db.py             # 数据库配置 DatabaseConfig（db_* 字段）
+├── redis.py          # Redis 配置 RedisConfig（redis_* 字段）
+├── log.py            # 日志配置 LogConfig（log_* 字段）
+├── security.py       # 安全配置 SecurityConfig（jwt_* 等字段）
+└── README.md         # 本文档
+```
+
+---
+
+## 3. 快速开始
+
+```python
+from jalontsui_fastapi_kit.config import BaseAppSettings
+
+settings = BaseAppSettings()
+
+print(settings.app_name)           # "app"（默认值）
+print(settings.app_env)            # "development"（默认值）
+print(settings.app_debug)          # False（默认值）
+print(settings.app_env == "development")  # True，也可用 is_development 属性
+print(settings.log_level)          # None（默认值）
+print(settings.log_path)           # "logs"（默认值）
+print(settings.log_filename)       # "app.log"（默认值）
+print(settings.db_host)            # "localhost"（默认值）
+print(settings.redis_port)         # 6379（默认值）
+```
+
+---
+
+## 4. 配置读取优先级
+
+pydantic-settings 读取优先级（高 → 低）：
+
+1. 环境变量
+2. 当前工作目录下的 `.env` 文件（或 `ENV_FILE` 指定的配置文件）
+3. 类中定义的默认值
+
+字段统一携带分块前缀，**环境变量名即字段名的大写形式**（大小写不敏感），无需嵌套分隔符。示例 `.env`：
+
+```env
+APP_NAME=jalontsui-web
+APP_ENV=production
+APP_DEBUG=true
+LOG_LEVEL=INFO
+LOG_PATH=logs
+DB_HOST=localhost
+DB_PORT=3306
+REDIS_HOST=localhost
+REDIS_PORT=6379
+```
+
+```python
+from jalontsui_fastapi_kit.config import BaseAppSettings
+
+settings = BaseAppSettings()
+print(settings.app_name)  # "jalontsui-web"
+print(settings.app_env)   # "production"
+```
+
+---
+
+## 5. 继承扩展
+
+业务项目应继承 `BaseAppSettings`，直接重定义字段即可覆盖默认值，并添加业务专属字段：
+
+```python
+from pydantic import Field
+from jalontsui_fastapi_kit.config import BaseAppSettings
+
+
+class AppSettings(BaseAppSettings):
+    """业务应用配置."""
+
+    # 覆盖通用配置默认值
+    app_name: str = Field(default="my-service")
+    db_name: str = Field(default="my_db")
+
+    # 业务专属字段
+    database_url: str = Field(
+        default="mysql+asyncmy://root@localhost:3306/mydb",
+        description="异步数据库连接串",
+    )
+    secret_key: str = Field(
+        default="change-me",
+        description="JWT / 加密密钥",
+    )
+
+
+settings = AppSettings()
+print(settings.app_name)      # "my-service"（覆盖后的默认值）
+print(settings.log_path)      # "logs"（继承自通用配置）
+print(settings.database_url)  # 业务自定义字段
+```
+
+> 字段名大小写不敏感（`case_sensitive=False`），`database_url` 与 `DATABASE_URL` 等价。
+
+若业务方不需要全部配置分块，也可自行组合，例如网关不需要数据库配置：
+
+```python
+from jalontsui_fastapi_kit.config import BaseAppConfig, AppConfig, LogConfig, RedisConfig
+
+
+class GatewaySettings(BaseAppConfig, AppConfig, LogConfig, RedisConfig):
+    """网关配置，仅组合所需分块."""
+```
+
+---
+
+## 6. 环境判断属性
+
+`AppConfig` 提供三个便捷属性：
+
+```python
+from jalontsui_fastapi_kit.config import BaseAppSettings
+
+settings = BaseAppSettings(app_env="production")
+
+assert settings.is_production is True
+assert settings.is_development is False
+assert settings.is_testing is False
+```
+
+常用于根据环境调整行为：
+
+```python
+if settings.is_development:
+    enable_auto_reload()
+```
+
+---
+
+## 7. 最佳实践
+
+- **业务项目必须继承扩展**：不要在业务代码中直接使用裸 `BaseAppSettings`。
+- **敏感字段走环境变量**：`jwt_secret_key`、数据库密码等不要写进代码或提交默认值。
+- **集中单例管理**：通常在业务包的 `config.py` 中实例化一次全局 `settings`，供全应用引用。
+- **字段描述要完整**：使用 `Field(description=...)` 说明用途，便于生成文档和 `.env.example`。
+- **新增配置分块**：参考 `packages/jalontsui-fastapi-kit/AGENTS.md` 第 2 节的标准流程，字段统一携带分块前缀。

jalontsui_fastapi_kit/config/__init__.py

@@ -0,0 +1,50 @@
+"""通用应用配置.
+
+本包按功能域拆分到多个模块，每个配置分块都是 BaseAppConfig 的子类，
+字段统一携带分块前缀（如 ``app_name`` / ``db_host`` / ``redis_host``）。
+BaseAppSettings 通过多继承直接组合各配置分块，使用方实例化一次即可扁平地
+读取全部配置（如 ``settings.app_name`` / ``settings.db_host``）。
+环境变量名与字段名一一对应（大小写不敏感），例如 ``APP_NAME``、``DB_HOST``。
+"""
+
+from __future__ import annotations
+
+from jalontsui_fastapi_kit.config.app import AppConfig
+from jalontsui_fastapi_kit.config.base import BaseAppConfig
+from jalontsui_fastapi_kit.config.common import CommonConfig
+from jalontsui_fastapi_kit.config.db import DatabaseConfig
+from jalontsui_fastapi_kit.config.log import LogConfig
+from jalontsui_fastapi_kit.config.redis import RedisConfig
+from jalontsui_fastapi_kit.config.security import SecurityConfig
+from jalontsui_fastapi_kit.config.storage import StorageConfig
+
+
+class BaseAppSettings(
+    AppConfig,
+    CommonConfig,
+    DatabaseConfig,
+    RedisConfig,
+    LogConfig,
+    SecurityConfig,
+    StorageConfig,
+):
+    """默认装配的通用应用配置.
+
+    通过多继承直接组合 app、common、db、redis、log、security 与 storage 七个通用配置域
+    （各分块本身已继承 BaseAppConfig，此处无需重复列出，否则会产生 MRO 冲突），
+    所有字段以 ``<分块>_`` 前缀扁平展开，可直接通过 ``settings.app_name`` 等方式访问。
+    如果业务方需要自定义装配其他配置域，可自行继承 BaseAppConfig 与所需配置分块组合。
+    """
+
+
+__all__ = [
+    "AppConfig",
+    "BaseAppConfig",
+    "BaseAppSettings",
+    "CommonConfig",
+    "DatabaseConfig",
+    "LogConfig",
+    "RedisConfig",
+    "SecurityConfig",
+    "StorageConfig",
+]

jalontsui_fastapi_kit/config/app.py

@@ -0,0 +1,46 @@
+"""应用基础配置."""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import Field
+
+from jalontsui_fastapi_kit.config.base import BaseAppConfig
+
+
+class AppConfig(BaseAppConfig):
+    """应用基础配置.
+
+    主要包含应用名称、运行环境、调试开关等通用元信息。
+    字段统一携带 ``app_`` 前缀，环境变量名即字段名的大写形式
+    （如 ``APP_NAME`` / ``APP_ENV`` / ``APP_DEBUG``）。
+    """
+
+    app_name: str = Field(
+        default="app",
+        description="应用名称，主要用于日志与文档展示",
+    )
+    app_env: Literal["development", "testing", "production"] = Field(
+        default="development",
+        description="应用运行环境，影响日志级别等默认行为",
+    )
+    app_debug: bool = Field(
+        default=False,
+        description="调试模式，开启后会输出更详细的错误信息",
+    )
+
+    @property
+    def is_development(self) -> bool:
+        """是否为开发环境."""
+        return self.app_env == "development"
+
+    @property
+    def is_testing(self) -> bool:
+        """是否为测试环境."""
+        return self.app_env == "testing"
+
+    @property
+    def is_production(self) -> bool:
+        """是否为生产环境."""
+        return self.app_env == "production"