jalontsui-fastapi-kit 0.1.0__tar.gz

jalontsui_fastapi_kit-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 JalonTsui (jalontsui@163.com)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

jalontsui_fastapi_kit-0.1.0/PKG-INFO

@@ -0,0 +1,136 @@
+Metadata-Version: 2.4
+Name: jalontsui-fastapi-kit
+Version: 0.1.0
+Summary: JalonTsui Fastapi Kit：FastAPI 服务公共基础设施包（配置、数据库、缓存、日志、错误体系、安全、中间件等）
+Keywords: fastapi,toolkit,infrastructure,backend,jwt,sqlalchemy,redis
+Author: JalonTsui
+Author-email: JalonTsui <jalontsui@163.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Framework :: FastAPI
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: pydantic>=2.10.0
+Requires-Dist: pydantic-settings>=2.7.0
+Requires-Dist: sqlalchemy[asyncio]>=2.0.40
+Requires-Dist: passlib[bcrypt]>=1.7.4
+Requires-Dist: bcrypt>=4.0.0,<4.1.0
+Requires-Dist: pyjwt[crypto]>=2.10.0
+Requires-Dist: redis>=5.0.0,<6.0
+Requires-Dist: tzlocal>=5.0
+Requires-Dist: pillow>=10.0.0 ; extra == 'captcha'
+Requires-Dist: asyncmy>=0.2.10 ; extra == 'mysql'
+Requires-Dist: pymysql>=1.1.1 ; extra == 'mysql'
+Requires-Dist: aioboto3>=15.5.0 ; extra == 'storage'
+Requires-Python: >=3.11
+Project-URL: Homepage, https://gitee.com/jalontsui/jalontsui-py-magic/tree/main/packages/jalontsui-fastapi-kit
+Project-URL: Repository, https://gitee.com/jalontsui/jalontsui-py-magic
+Provides-Extra: captcha
+Provides-Extra: mysql
+Provides-Extra: storage
+Description-Content-Type: text/markdown
+
+# JalonTsui Fastapi Kit
+
+面向 FastAPI 服务的公共基础设施包：配置、数据库、缓存、日志、错误体系、安全、中间件等通用能力一次装齐，业务包只做业务语义薄封装。
+
+| 项 | 值 |
+|----|----|
+| 发行名（安装名） | `jalontsui-fastapi-kit` |
+| import 名 | `jalontsui_fastapi_kit` |
+| Python 要求 | `>=3.11` |
+| 许可证 | MIT |
+
+## 安装
+
+```bash
+uv add jalontsui-fastapi-kit
+```
+
+按实际需要选装 extras（可组合，如 `[mysql,storage]`）：
+
+```bash
+uv add "jalontsui-fastapi-kit[mysql]"     # MySQL 驱动：asyncmy（异步）+ pymysql（同步 / Alembic 迁移）
+uv add "jalontsui-fastapi-kit[captcha]"   # 图形验证码：Pillow
+uv add "jalontsui-fastapi-kit[storage]"   # S3 协议对象存储：aioboto3
+```
+
+核心依赖只包含 FastAPI / Pydantic / SQLAlchemy / Redis 等基础库；数据库驱动与 Pillow 均为可选，纯工具脚本不会被强迫安装 MySQL 驱动。驱动缺失时，创建数据库引擎会抛出带安装提示的中文报错。
+
+发布前也可从 Git 直装（monorepo subdirectory 方式）：
+
+```bash
+uv add "git+https://gitee.com/jalontsui/jalontsui-py-magic.git@jalontsui-fastapi-kit-v0.1.0#subdirectory=packages/jalontsui-fastapi-kit"
+```
+
+## 快速上手
+
+```python
+from jalontsui_fastapi_kit.config import BaseAppSettings
+from jalontsui_fastapi_kit.response import ApiResponse
+
+
+class Settings(BaseAppSettings):
+    """业务配置继承基类，即获得全部通用配置字段."""
+
+    app_name: str = "my-service"
+    db_name: str = "my_db"
+
+
+settings = Settings()
+
+# 统一响应结构
+content = ApiResponse.ok(data={"id": 1})
+```
+
+创建数据库引擎（`mysql+asyncmy` 等驱动需先安装 `[mysql]` extra）：
+
+```python
+from jalontsui_fastapi_kit.db import create_async_engine_from_url
+
+engine = create_async_engine_from_url(settings.build_db_async_url())
+```
+
+## 能力清单
+
+| 能力 | 导入路径 | 使用文档 |
+|------|----------|----------|
+| 统一响应结构 | `jalontsui_fastapi_kit.response.ApiResponse` | — |
+| 业务异常体系与错误码 | `jalontsui_fastapi_kit.errors` | [使用指南](https://gitee.com/jalontsui/jalontsui-py-magic/blob/main/packages/jalontsui-fastapi-kit/src/jalontsui_fastapi_kit/errors/README.md) |
+| 全局异常处理器 | `jalontsui_fastapi_kit.errors.handlers` | [使用指南](https://gitee.com/jalontsui/jalontsui-py-magic/blob/main/packages/jalontsui-fastapi-kit/src/jalontsui_fastapi_kit/errors/README.md) |
+| 应用配置基类与配置分块 | `jalontsui_fastapi_kit.config.BaseAppSettings` | [使用指南](https://gitee.com/jalontsui/jalontsui-py-magic/blob/main/packages/jalontsui-fastapi-kit/src/jalontsui_fastapi_kit/config/README.md) |
+| 数据库基类与异步引擎工厂 | `jalontsui_fastapi_kit.db` / `create_async_engine_from_url` | [使用指南](https://gitee.com/jalontsui/jalontsui-py-magic/blob/main/packages/jalontsui-fastapi-kit/src/jalontsui_fastapi_kit/db/README.md) |
+| 可嵌套事务上下文 | `jalontsui_fastapi_kit.db.transaction` | [使用指南](https://gitee.com/jalontsui/jalontsui-py-magic/blob/main/packages/jalontsui-fastapi-kit/src/jalontsui_fastapi_kit/db/README.md) |
+| 通用 Repository | `jalontsui_fastapi_kit.repositories.base.BaseRepository` | [使用指南](https://gitee.com/jalontsui/jalontsui-py-magic/blob/main/packages/jalontsui-fastapi-kit/src/jalontsui_fastapi_kit/repositories/README.md) |
+| Service 基类 | `jalontsui_fastapi_kit.services.base.BaseService` | [使用指南](https://gitee.com/jalontsui/jalontsui-py-magic/blob/main/packages/jalontsui-fastapi-kit/src/jalontsui_fastapi_kit/services/README.md) |
+| Redis 客户端 | `jalontsui_fastapi_kit.cache` | [使用指南](https://gitee.com/jalontsui/jalontsui-py-magic/blob/main/packages/jalontsui-fastapi-kit/src/jalontsui_fastapi_kit/cache/README.md) |
+| 健康检查框架 | `jalontsui_fastapi_kit.health` | [使用指南](https://gitee.com/jalontsui/jalontsui-py-magic/blob/main/packages/jalontsui-fastapi-kit/src/jalontsui_fastapi_kit/health/README.md) |
+| 请求追踪 / CORS / 语言中间件 | `jalontsui_fastapi_kit.middleware` | [使用指南](https://gitee.com/jalontsui/jalontsui-py-magic/blob/main/packages/jalontsui-fastapi-kit/src/jalontsui_fastapi_kit/middleware/README.md) |
+| 结构化日志 | `jalontsui_fastapi_kit.logging` | [使用指南](https://gitee.com/jalontsui/jalontsui-py-magic/blob/main/packages/jalontsui-fastapi-kit/src/jalontsui_fastapi_kit/logging/README.md) |
+| 密码哈希 / JWT / 图形验证码 | `jalontsui_fastapi_kit.security` | [使用指南](https://gitee.com/jalontsui/jalontsui-py-magic/blob/main/packages/jalontsui-fastapi-kit/src/jalontsui_fastapi_kit/security/README.md) |
+| 分页 Schema | `jalontsui_fastapi_kit.schemas.common` | [使用指南](https://gitee.com/jalontsui/jalontsui-py-magic/blob/main/packages/jalontsui-fastapi-kit/src/jalontsui_fastapi_kit/schemas/README.md) |
+| 参数校验格式化 | `jalontsui_fastapi_kit.validation` | [使用指南](https://gitee.com/jalontsui/jalontsui-py-magic/blob/main/packages/jalontsui-fastapi-kit/src/jalontsui_fastapi_kit/validation/README.md) |
+| 搜索引擎扩展位 | `jalontsui_fastapi_kit.search` | [使用指南](https://gitee.com/jalontsui/jalontsui-py-magic/blob/main/packages/jalontsui-fastapi-kit/src/jalontsui_fastapi_kit/search/README.md) |
+
+## 设计原则
+
+- **零业务依赖**：本包只允许依赖通用第三方库，禁止依赖任何业务包。
+- **业务包优先复用**：新增通用能力先在本包实现，业务侧做薄层封装或直接导入。
+- **业务专属留在业务包**：业务错误码、业务 Service / Repository、业务配置不进入本包。
+
+## 边界
+
+- 不包含 MinIO / Qdrant / Celery 等业务中间件。
+- 数据库驱动（asyncmy / pymysql）与 Pillow 为可选依赖，见上文 extras。
+
+## 版本与协议
+
+- 版本记录：[CHANGELOG.md](https://gitee.com/jalontsui/jalontsui-py-magic/blob/main/packages/jalontsui-fastapi-kit/CHANGELOG.md)。
+- 许可证：[MIT](https://gitee.com/jalontsui/jalontsui-py-magic/blob/main/packages/jalontsui-fastapi-kit/LICENSE)。

jalontsui_fastapi_kit-0.1.0/README.md

@@ -0,0 +1,97 @@
+# JalonTsui Fastapi Kit
+
+面向 FastAPI 服务的公共基础设施包：配置、数据库、缓存、日志、错误体系、安全、中间件等通用能力一次装齐，业务包只做业务语义薄封装。
+
+| 项 | 值 |
+|----|----|
+| 发行名（安装名） | `jalontsui-fastapi-kit` |
+| import 名 | `jalontsui_fastapi_kit` |
+| Python 要求 | `>=3.11` |
+| 许可证 | MIT |
+
+## 安装
+
+```bash
+uv add jalontsui-fastapi-kit
+```
+
+按实际需要选装 extras（可组合，如 `[mysql,storage]`）：
+
+```bash
+uv add "jalontsui-fastapi-kit[mysql]"     # MySQL 驱动：asyncmy（异步）+ pymysql（同步 / Alembic 迁移）
+uv add "jalontsui-fastapi-kit[captcha]"   # 图形验证码：Pillow
+uv add "jalontsui-fastapi-kit[storage]"   # S3 协议对象存储：aioboto3
+```
+
+核心依赖只包含 FastAPI / Pydantic / SQLAlchemy / Redis 等基础库；数据库驱动与 Pillow 均为可选，纯工具脚本不会被强迫安装 MySQL 驱动。驱动缺失时，创建数据库引擎会抛出带安装提示的中文报错。
+
+发布前也可从 Git 直装（monorepo subdirectory 方式）：
+
+```bash
+uv add "git+https://gitee.com/jalontsui/jalontsui-py-magic.git@jalontsui-fastapi-kit-v0.1.0#subdirectory=packages/jalontsui-fastapi-kit"
+```
+
+## 快速上手
+
+```python
+from jalontsui_fastapi_kit.config import BaseAppSettings
+from jalontsui_fastapi_kit.response import ApiResponse
+
+
+class Settings(BaseAppSettings):
+    """业务配置继承基类，即获得全部通用配置字段."""
+
+    app_name: str = "my-service"
+    db_name: str = "my_db"
+
+
+settings = Settings()
+
+# 统一响应结构
+content = ApiResponse.ok(data={"id": 1})
+```
+
+创建数据库引擎（`mysql+asyncmy` 等驱动需先安装 `[mysql]` extra）：
+
+```python
+from jalontsui_fastapi_kit.db import create_async_engine_from_url
+
+engine = create_async_engine_from_url(settings.build_db_async_url())
+```
+
+## 能力清单
+
+| 能力 | 导入路径 | 使用文档 |
+|------|----------|----------|
+| 统一响应结构 | `jalontsui_fastapi_kit.response.ApiResponse` | — |
+| 业务异常体系与错误码 | `jalontsui_fastapi_kit.errors` | [使用指南](https://gitee.com/jalontsui/jalontsui-py-magic/blob/main/packages/jalontsui-fastapi-kit/src/jalontsui_fastapi_kit/errors/README.md) |
+| 全局异常处理器 | `jalontsui_fastapi_kit.errors.handlers` | [使用指南](https://gitee.com/jalontsui/jalontsui-py-magic/blob/main/packages/jalontsui-fastapi-kit/src/jalontsui_fastapi_kit/errors/README.md) |
+| 应用配置基类与配置分块 | `jalontsui_fastapi_kit.config.BaseAppSettings` | [使用指南](https://gitee.com/jalontsui/jalontsui-py-magic/blob/main/packages/jalontsui-fastapi-kit/src/jalontsui_fastapi_kit/config/README.md) |
+| 数据库基类与异步引擎工厂 | `jalontsui_fastapi_kit.db` / `create_async_engine_from_url` | [使用指南](https://gitee.com/jalontsui/jalontsui-py-magic/blob/main/packages/jalontsui-fastapi-kit/src/jalontsui_fastapi_kit/db/README.md) |
+| 可嵌套事务上下文 | `jalontsui_fastapi_kit.db.transaction` | [使用指南](https://gitee.com/jalontsui/jalontsui-py-magic/blob/main/packages/jalontsui-fastapi-kit/src/jalontsui_fastapi_kit/db/README.md) |
+| 通用 Repository | `jalontsui_fastapi_kit.repositories.base.BaseRepository` | [使用指南](https://gitee.com/jalontsui/jalontsui-py-magic/blob/main/packages/jalontsui-fastapi-kit/src/jalontsui_fastapi_kit/repositories/README.md) |
+| Service 基类 | `jalontsui_fastapi_kit.services.base.BaseService` | [使用指南](https://gitee.com/jalontsui/jalontsui-py-magic/blob/main/packages/jalontsui-fastapi-kit/src/jalontsui_fastapi_kit/services/README.md) |
+| Redis 客户端 | `jalontsui_fastapi_kit.cache` | [使用指南](https://gitee.com/jalontsui/jalontsui-py-magic/blob/main/packages/jalontsui-fastapi-kit/src/jalontsui_fastapi_kit/cache/README.md) |
+| 健康检查框架 | `jalontsui_fastapi_kit.health` | [使用指南](https://gitee.com/jalontsui/jalontsui-py-magic/blob/main/packages/jalontsui-fastapi-kit/src/jalontsui_fastapi_kit/health/README.md) |
+| 请求追踪 / CORS / 语言中间件 | `jalontsui_fastapi_kit.middleware` | [使用指南](https://gitee.com/jalontsui/jalontsui-py-magic/blob/main/packages/jalontsui-fastapi-kit/src/jalontsui_fastapi_kit/middleware/README.md) |
+| 结构化日志 | `jalontsui_fastapi_kit.logging` | [使用指南](https://gitee.com/jalontsui/jalontsui-py-magic/blob/main/packages/jalontsui-fastapi-kit/src/jalontsui_fastapi_kit/logging/README.md) |
+| 密码哈希 / JWT / 图形验证码 | `jalontsui_fastapi_kit.security` | [使用指南](https://gitee.com/jalontsui/jalontsui-py-magic/blob/main/packages/jalontsui-fastapi-kit/src/jalontsui_fastapi_kit/security/README.md) |
+| 分页 Schema | `jalontsui_fastapi_kit.schemas.common` | [使用指南](https://gitee.com/jalontsui/jalontsui-py-magic/blob/main/packages/jalontsui-fastapi-kit/src/jalontsui_fastapi_kit/schemas/README.md) |
+| 参数校验格式化 | `jalontsui_fastapi_kit.validation` | [使用指南](https://gitee.com/jalontsui/jalontsui-py-magic/blob/main/packages/jalontsui-fastapi-kit/src/jalontsui_fastapi_kit/validation/README.md) |
+| 搜索引擎扩展位 | `jalontsui_fastapi_kit.search` | [使用指南](https://gitee.com/jalontsui/jalontsui-py-magic/blob/main/packages/jalontsui-fastapi-kit/src/jalontsui_fastapi_kit/search/README.md) |
+
+## 设计原则
+
+- **零业务依赖**：本包只允许依赖通用第三方库，禁止依赖任何业务包。
+- **业务包优先复用**：新增通用能力先在本包实现，业务侧做薄层封装或直接导入。
+- **业务专属留在业务包**：业务错误码、业务 Service / Repository、业务配置不进入本包。
+
+## 边界
+
+- 不包含 MinIO / Qdrant / Celery 等业务中间件。
+- 数据库驱动（asyncmy / pymysql）与 Pillow 为可选依赖，见上文 extras。
+
+## 版本与协议
+
+- 版本记录：[CHANGELOG.md](https://gitee.com/jalontsui/jalontsui-py-magic/blob/main/packages/jalontsui-fastapi-kit/CHANGELOG.md)。
+- 许可证：[MIT](https://gitee.com/jalontsui/jalontsui-py-magic/blob/main/packages/jalontsui-fastapi-kit/LICENSE)。

jalontsui_fastapi_kit-0.1.0/pyproject.toml

@@ -0,0 +1,66 @@
+[project]
+name = "jalontsui-fastapi-kit"
+version = "0.1.0"
+description = "JalonTsui Fastapi Kit：FastAPI 服务公共基础设施包（配置、数据库、缓存、日志、错误体系、安全、中间件等）"
+readme = "README.md"
+authors = [
+    { name = "JalonTsui", email = "jalontsui@163.com" }
+]
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Framework :: FastAPI",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+keywords = ["fastapi", "toolkit", "infrastructure", "backend", "jwt", "sqlalchemy", "redis"]
+dependencies = [
+    "fastapi>=0.115.0",            # Web 框架依赖，用于中间件、依赖注入与响应类型
+    "pydantic>=2.10.0",            # 数据校验与序列化
+    "pydantic-settings>=2.7.0",    # 基于 Pydantic 的配置管理（支持 .env）
+    "sqlalchemy[asyncio]>=2.0.40", # ORM 与异步数据库连接抽象
+    "passlib[bcrypt]>=1.7.4",      # 密码哈希
+    "bcrypt>=4.0.0,<4.1.0",        # 与 passlib 1.7.4 兼容的 bcrypt 版本
+    "pyjwt[crypto]>=2.10.0",       # JWT 加解密（替代停更的 python-jose，见 TODO 第 45 条）
+    "redis>=5.0.0,<6.0",           # Redis 客户端，用于健康检查与缓存场景
+    "tzlocal>=5.0",                # 获取服务器本地时区（IANA），用于默认时区展示
+]
+
+[project.optional-dependencies]
+# 数据库驱动由消费方按实际数据库选装：uv add "jalontsui-fastapi-kit[mysql]"
+mysql = [
+    "asyncmy>=0.2.10", # MySQL 异步驱动
+    "pymysql>=1.1.1",  # MySQL 同步驱动（Alembic 等场景使用）
+]
+# 图形验证码依赖 Pillow：uv add "jalontsui-fastapi-kit[captcha]"
+captcha = [
+    "pillow>=10.0.0",
+]
+storage = [
+    "aioboto3>=15.5.0",
+]
+
+[project.urls]
+Homepage = "https://gitee.com/jalontsui/jalontsui-py-magic/tree/main/packages/jalontsui-fastapi-kit"
+Repository = "https://gitee.com/jalontsui/jalontsui-py-magic"
+
+[build-system]
+requires = ["uv_build>=0.11.15,<0.12.0"]
+build-backend = "uv_build"
+
+# 显式声明 uv_build 的模块名与模块根目录，避免改名或自动推导时踩坑
+[tool.uv.build-backend]
+module-name = "jalontsui_fastapi_kit"
+module-root = "src"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "session"
+asyncio_default_test_loop_scope = "session"

jalontsui_fastapi_kit-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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",
+]