springbootAI 2.2.3__tar.gz → 2.2.5__tar.gz

{springbootai-2.2.3 → springbootai-2.2.5}/CHANGELOG.md

@@ -1,12 +1,41 @@
 # Changelog
 
+## [2.2.5] - 2026-08-14
+
+### 新增
+
+- **Spring Boot Admin 风格可视化面板**：访问 `/actuator/admin` 即可在浏览器查看整合后的 HTML 仪表盘，包含健康状态、系统信息、内存 & CPU、线程概览、日志级别管理（点击切换）、Prometheus 指标（原始数据 + 摘要表格）、Bean 列表七大区块。每 30 秒自动刷新，无需独立部署 Admin Server。
+- **Prometheus 指标暴露端点** `/actuator/prometheus`：以 Prometheus 文本格式（`text/plain; version=0.0.4`）暴露应用指标，供 Prometheus Server 抓取。支持多 worker 部署（`PROMETHEUS_MULTIPROC_DIR`），未安装 `prometheus_client` 时返回 503。
+- **进程系统指标端点** `/actuator/sysmetrics`：通过 `psutil` 采集进程级 RSS、虚拟内存、CPU 使用率、线程数、文件描述符数。
+- **ORM 分页查询注解 `@SelectPage`**：自动提取 `page_num`/`page_size` 参数并返回 `{total, page_num, page_size, data}` 结构，支持 `pageNum`/`page`/`pageSize`/`size` 等参数名变体，可自定义 COUNT 语句。
+
+### 文档
+
+- `doc/ACTUATOR_MODULE.md` 新增第四章（Spring Boot Admin 可视化面板）、第五章（Prometheus + Grafana 工业级监控，含三步接入流程与多 worker 注意事项）、第六章（自定义业务指标）。
+- `doc/ORM_MODULE.md` 第五章新增"方法 1：@SelectPage 注解（推荐）"小节。
+- `README.md` 4.8 健康检查表新增 `/actuator/admin`、`/actuator/prometheus`、`/actuator/sysmetrics` 三个端点。
+- `doc/EIGHT_MODULES.md` Actuator 模块说明补充"Spring Boot Admin 可视化 + Prometheus 指标"。
+
+### 测试
+
+- 新增 `tests/test_actuator_prometheus_admin.py`（9 项测试全部通过）：覆盖 Prometheus 端点格式、Admin 面板 HTML、sysmetrics 端点、端点目录。
+- 新增 `tests/test_select_page.py`：覆盖 `@SelectPage` 分页注解。
+
+## [2.2.4] - 2026-08-13
+
+### 完善
+
+- 自动推断逻辑调整：无赋值的字段仅创建 `Column()` 记录类型，不设默认值；只有显式赋值才作为 `default`。
+- `_parse_entity` 跳过以 `_` 开头的私有字段，不生成 DDL 列。
+- 新增 `example_all/models/EntityModels.py` 实体示例和 `test_06_entity_jpa_style` 测试（4 项全通过）。
+
 ## [2.2.3] - 2026-08-13
 
 ### 新增
 
 - ORM 实体字段自动推断：类型注解无需显式 `= Column(...)` 赋值，对齐 Java JPA 字段自动映射。
-  - `name: str` → 自动创建 `Column(default=None)`
-  - `name: str = ""` → 自动创建 `Column(default="")`
+  - `name: str` → 自动创建 `Column()`（无默认值，仅记录类型）
+  - `name: str = ""` → 自动创建 `Column(default="")`（赋值即为默认值）
   - `name: int = 0` → 自动创建 `Column(default=0)`
   - 已有 `Column()`/`Id()`/`CreateTime()` 等描述符的字段保留不覆盖
   - 以 `_` 开头的私有字段自动跳过

{springbootai-2.2.3/springbootAI.egg-info → springbootai-2.2.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: springbootAI
-Version: 2.2.3
+Version: 2.2.5
 Summary: Spring-style Python framework with Web, ORM, Cloud and AI integrations
 Author-email: YuConggen <1516933915@qq.com>
 License-Expression: MIT
@@ -252,13 +252,21 @@ curl http://127.0.0.1:8080/api/hello/Alice
 | 📦 LangGraph | [LANGGRAPH_MODULE.md](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/LANGGRAPH_MODULE.md) | `pip install springbootAI[langgraph]` | 状态图 / 条件路由 / 人工中断 / 注解式工作流 |
 | 📦 MCP | [MCP_MODULE.md](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/MCP_MODULE.md) | `pip install springbootAI[mcp]` | MCP Client / Server / Tool / Resource / Prompt / 注解调用 |
 | ✅ 内嵌 PyMyBatis ORM | [ORM_MODULE.md](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/ORM_MODULE.md) | 随核心包 | Mapper 注解 / XML Mapper / 分页 / SQL 安全 / DDL 自动建表 |
+| ✅ JPA 实体与仓库 | [JPA_MODULE.md](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/JPA_MODULE.md) | 随核心包 | `@Entity` + `@Table` / 字段自动推断 / `@CreateTime` / Repository / DataJpaTest |
 | ✅ Cloud 微服务 | [CLOUD_MODULE.md](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/CLOUD_MODULE.md) | 随核心包 | 服务注册发现 / 配置刷新 / Feign / Sentinel / Gateway / 分布式事务 |
 | 📦 Excel 读写 | [EXCEL_MODULE.md](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/EXCEL_MODULE.md) | `pip install springbootAI[excel]` | `@ExcelProperty` / `@ExcelIgnore` 注解驱动读写 |
 | 📦 CSV 读写 | [CSV_MODULE.md](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/CSV_MODULE.md) | `pip install springbootAI[csv]` | `@CsvProperty` / `@CsvIgnore` 注解驱动读写 |
 | ✅ Swagger 文档 | [SWAGGER_MODULE.md](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/SWAGGER_MODULE.md) | 随核心包 | `@Tag` / `@Operation` 注解驱动 API 文档 |
-| ✅ 八大模块 | [EIGHT_MODULES.md](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/EIGHT_MODULES.md) | 随核心包 | 分页 / Actuator / 多数据源 / i18n / WebSocket 等 |
 | ✅ 安全 | [SECURITY.md](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/SECURITY.md) | 随核心包 | JWT 生成校验 / 密码加密 / SQL 注入防护 / 访问控制 |
 | ✅ BeanUtils | [BEAN_UTILS.md](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/BEAN_UTILS.md) | 随核心包 | `copy_properties` / `clone` 属性复制工具 |
+| ✅ ① Repository | [REPOSITORY_MODULE.md](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/REPOSITORY_MODULE.md) | 随核心包 | 不用手写SQL的分页查询 |
+| ✅ ② Actuator | [ACTUATOR_MODULE.md](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/ACTUATOR_MODULE.md) | 随核心包 | 系统健康检查面板 |
+| ✅ ③ 多数据源 | [DATASOURCE_MODULE.md](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/DATASOURCE_MODULE.md) | 随核心包 | 读写分离 |
+| ✅ ④ 事务事件 | [TX_EVENT_MODULE.md](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/TX_EVENT_MODULE.md) | 随核心包 | 操作完成后自动发通知 |
+| ✅ ⑤ 配置绑定 | [CONFIG_BINDING_MODULE.md](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/CONFIG_BINDING_MODULE.md) | 随核心包 | 把YAML配置自动变成Python对象 |
+| ✅ ⑥ 测试切片 | [TEST_SLICE_MODULE.md](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/TEST_SLICE_MODULE.md) | 随核心包 | 只测试你关心的部分 |
+| ✅ ⑦ i18n | [I18N_MODULE.md](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/I18N_MODULE.md) | 随核心包 | 中英文自动切换 |
+| ✅ ⑧ WebSocket | [WEBSOCKET_MODULE.md](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/WEBSOCKET_MODULE.md) | 随核心包 | 像微信一样实时通信 |
 | — AI 与 LangChain 测试 | [AI_LANGCHAIN_TEST_GUIDE.md](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/AI_LANGCHAIN_TEST_GUIDE.md) | — | AI 与 LangChain 测试说明 |
 | — 测试报告 | [TEST_REPORT.md](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/TEST_REPORT.md) | — | 全量测试用例与覆盖范围 |
 
@@ -474,7 +482,7 @@ python -c "from spring.orm.pymybatis import __version__; print(__version__)"
 
 ### 3.5 最小应用
 
-仓库中的 `example`、`example1`、`example5` 只用于源码参考和回归验证，不会打包进 `springbootAI`。安装后请按下面结构创建自己的应用包。**每个被扫描目录都必须包含 `__init__.py`，并从项目根目录启动。**
+仓库中的 `example_all`、`example_langchain`、`example_langgraph`、`example_mcp`、`test_cloud_app` 只用于源码参考和回归验证，不会打包进 `springbootAI`。安装后请按下面结构创建自己的应用包。**每个被扫描目录都必须包含 `__init__.py`，并从项目根目录启动。**
 
 创建包结构：
 
@@ -681,9 +689,14 @@ Profile 用于 Bean 过滤和生产安全校验。多环境配置可使用以下
 | `/actuator/health/liveness` | 进程存活检查（用于 K8s livenessProbe） |
 | `/actuator/health/readiness` | 服务就绪检查（用于 K8s readinessProbe） |
 | `/actuator/info` | 应用名称、当前 Profile、框架和 Python 版本 |
+| `/actuator/admin` | **Spring Boot Admin 风格可视化面板**（浏览器打开即用，每 30 秒自动刷新） |
+| `/actuator/prometheus` | **Prometheus 文本格式指标**（供 Prometheus Server 抓取） |
+| `/actuator/sysmetrics` | **进程级系统指标**（RSS/CPU/线程/FD，供 Admin 面板 JS 调用） |
 
 `database.enabled: false` 时数据库状态为 `DISABLED`，不会创建 `test.db`。
 
+> 详见 [ACTUATOR_MODULE.md](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/ACTUATOR_MODULE.md) 第四章（Spring Boot Admin 面板）与第五章（Prometheus + Grafana 工业级监控）。
+
 > **⚠️ 新手常见错误**：
 > - ❌ 错误："我改了 YAML，重新请求接口怎么没生效？"
 > - ✅ 正解：修改 YAML 后需要**重启应用**（`Ctrl+C` 停掉再重新运行）。YAML 配置是启动时一次性读取的。
@@ -1647,7 +1660,7 @@ curl http://localhost:8080/actuator/health
 
 ## 15. 项目结构
 
-`example`、`example1`、`example5`、`example_langchain` 是仓库级示例，不属于 `springbootAI` 安装包。实际项目应创建自己的应用包。
+`example_all`、`example_langchain`、`example_langgraph`、`example_mcp`、`test_cloud_app` 是仓库级示例，不属于 `springbootAI` 安装包。实际项目应创建自己的应用包。
 
 推荐目录结构：
 

{springbootai-2.2.3 → springbootai-2.2.5}/README.md

@@ -118,13 +118,21 @@ curl http://127.0.0.1:8080/api/hello/Alice
 | 📦 LangGraph | [LANGGRAPH_MODULE.md](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/LANGGRAPH_MODULE.md) | `pip install springbootAI[langgraph]` | 状态图 / 条件路由 / 人工中断 / 注解式工作流 |
 | 📦 MCP | [MCP_MODULE.md](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/MCP_MODULE.md) | `pip install springbootAI[mcp]` | MCP Client / Server / Tool / Resource / Prompt / 注解调用 |
 | ✅ 内嵌 PyMyBatis ORM | [ORM_MODULE.md](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/ORM_MODULE.md) | 随核心包 | Mapper 注解 / XML Mapper / 分页 / SQL 安全 / DDL 自动建表 |
+| ✅ JPA 实体与仓库 | [JPA_MODULE.md](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/JPA_MODULE.md) | 随核心包 | `@Entity` + `@Table` / 字段自动推断 / `@CreateTime` / Repository / DataJpaTest |
 | ✅ Cloud 微服务 | [CLOUD_MODULE.md](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/CLOUD_MODULE.md) | 随核心包 | 服务注册发现 / 配置刷新 / Feign / Sentinel / Gateway / 分布式事务 |
 | 📦 Excel 读写 | [EXCEL_MODULE.md](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/EXCEL_MODULE.md) | `pip install springbootAI[excel]` | `@ExcelProperty` / `@ExcelIgnore` 注解驱动读写 |
 | 📦 CSV 读写 | [CSV_MODULE.md](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/CSV_MODULE.md) | `pip install springbootAI[csv]` | `@CsvProperty` / `@CsvIgnore` 注解驱动读写 |
 | ✅ Swagger 文档 | [SWAGGER_MODULE.md](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/SWAGGER_MODULE.md) | 随核心包 | `@Tag` / `@Operation` 注解驱动 API 文档 |
-| ✅ 八大模块 | [EIGHT_MODULES.md](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/EIGHT_MODULES.md) | 随核心包 | 分页 / Actuator / 多数据源 / i18n / WebSocket 等 |
 | ✅ 安全 | [SECURITY.md](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/SECURITY.md) | 随核心包 | JWT 生成校验 / 密码加密 / SQL 注入防护 / 访问控制 |
 | ✅ BeanUtils | [BEAN_UTILS.md](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/BEAN_UTILS.md) | 随核心包 | `copy_properties` / `clone` 属性复制工具 |
+| ✅ ① Repository | [REPOSITORY_MODULE.md](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/REPOSITORY_MODULE.md) | 随核心包 | 不用手写SQL的分页查询 |
+| ✅ ② Actuator | [ACTUATOR_MODULE.md](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/ACTUATOR_MODULE.md) | 随核心包 | 系统健康检查面板 |
+| ✅ ③ 多数据源 | [DATASOURCE_MODULE.md](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/DATASOURCE_MODULE.md) | 随核心包 | 读写分离 |
+| ✅ ④ 事务事件 | [TX_EVENT_MODULE.md](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/TX_EVENT_MODULE.md) | 随核心包 | 操作完成后自动发通知 |
+| ✅ ⑤ 配置绑定 | [CONFIG_BINDING_MODULE.md](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/CONFIG_BINDING_MODULE.md) | 随核心包 | 把YAML配置自动变成Python对象 |
+| ✅ ⑥ 测试切片 | [TEST_SLICE_MODULE.md](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/TEST_SLICE_MODULE.md) | 随核心包 | 只测试你关心的部分 |
+| ✅ ⑦ i18n | [I18N_MODULE.md](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/I18N_MODULE.md) | 随核心包 | 中英文自动切换 |
+| ✅ ⑧ WebSocket | [WEBSOCKET_MODULE.md](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/WEBSOCKET_MODULE.md) | 随核心包 | 像微信一样实时通信 |
 | — AI 与 LangChain 测试 | [AI_LANGCHAIN_TEST_GUIDE.md](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/AI_LANGCHAIN_TEST_GUIDE.md) | — | AI 与 LangChain 测试说明 |
 | — 测试报告 | [TEST_REPORT.md](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/TEST_REPORT.md) | — | 全量测试用例与覆盖范围 |
 
@@ -340,7 +348,7 @@ python -c "from spring.orm.pymybatis import __version__; print(__version__)"
 
 ### 3.5 最小应用
 
-仓库中的 `example`、`example1`、`example5` 只用于源码参考和回归验证，不会打包进 `springbootAI`。安装后请按下面结构创建自己的应用包。**每个被扫描目录都必须包含 `__init__.py`，并从项目根目录启动。**
+仓库中的 `example_all`、`example_langchain`、`example_langgraph`、`example_mcp`、`test_cloud_app` 只用于源码参考和回归验证，不会打包进 `springbootAI`。安装后请按下面结构创建自己的应用包。**每个被扫描目录都必须包含 `__init__.py`，并从项目根目录启动。**
 
 创建包结构：
 
@@ -547,9 +555,14 @@ Profile 用于 Bean 过滤和生产安全校验。多环境配置可使用以下
 | `/actuator/health/liveness` | 进程存活检查（用于 K8s livenessProbe） |
 | `/actuator/health/readiness` | 服务就绪检查（用于 K8s readinessProbe） |
 | `/actuator/info` | 应用名称、当前 Profile、框架和 Python 版本 |
+| `/actuator/admin` | **Spring Boot Admin 风格可视化面板**（浏览器打开即用，每 30 秒自动刷新） |
+| `/actuator/prometheus` | **Prometheus 文本格式指标**（供 Prometheus Server 抓取） |
+| `/actuator/sysmetrics` | **进程级系统指标**（RSS/CPU/线程/FD，供 Admin 面板 JS 调用） |
 
 `database.enabled: false` 时数据库状态为 `DISABLED`，不会创建 `test.db`。
 
+> 详见 [ACTUATOR_MODULE.md](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/ACTUATOR_MODULE.md) 第四章（Spring Boot Admin 面板）与第五章（Prometheus + Grafana 工业级监控）。
+
 > **⚠️ 新手常见错误**：
 > - ❌ 错误："我改了 YAML，重新请求接口怎么没生效？"
 > - ✅ 正解：修改 YAML 后需要**重启应用**（`Ctrl+C` 停掉再重新运行）。YAML 配置是启动时一次性读取的。
@@ -1513,7 +1526,7 @@ curl http://localhost:8080/actuator/health
 
 ## 15. 项目结构
 
-`example`、`example1`、`example5`、`example_langchain` 是仓库级示例，不属于 `springbootAI` 安装包。实际项目应创建自己的应用包。
+`example_all`、`example_langchain`、`example_langgraph`、`example_mcp`、`test_cloud_app` 是仓库级示例，不属于 `springbootAI` 安装包。实际项目应创建自己的应用包。
 
 推荐目录结构：
 

{springbootai-2.2.3 → springbootai-2.2.5}/pyproject.toml

@@ -12,7 +12,7 @@ build-backend = "setuptools.build_meta"
 [project]
 # 发行名 springbootAI（PyPI 包名，pip install springbootAI）；导入包名仍为 spring
 name = "springbootAI"
-version = "2.2.3"
+version = "2.2.5"
 description = "Spring-style Python framework with Web, ORM, Cloud and AI integrations"
 readme = "README.md"
 license = "MIT"

{springbootai-2.2.3 → springbootai-2.2.5}/spring/orm/__init__.py

@@ -46,6 +46,7 @@ from spring.orm.mybatis_integration import (
 # 导入注解
 from spring.orm.pymybatis.annotations import (
     Select,
+    SelectPage,
     Insert,
     Update,
     Delete,
@@ -187,6 +188,7 @@ __all__ = [
     'init_mybatis',
     # 注解
     'Select',
+    'SelectPage',
     'Insert',
     'Update',
     'Delete',

{springbootai-2.2.3 → springbootai-2.2.5}/spring/orm/ddl_auto.py

@@ -1091,8 +1091,8 @@ def _auto_infer_columns(cls):
     无需显式 ``= Column(...)`` 赋值。
 
     推断规则：
-      - ``name: str``               → ``Column(default=None)``
-      - ``name: str = ""``          → ``Column(default="")``
+      - ``name: str``               → ``Column()``（无默认值，仅记录类型）
+      - ``name: str = ""``          → ``Column(default="")``（赋值即为默认值）
       - ``name: int = 0``           → ``Column(default=0)``
       - ``name: str = Column(...)`` → 保留原 Column，不覆盖
       - ``name: int = Id()``        → 保留原 Id，不覆盖
@@ -1130,14 +1130,14 @@ def _auto_infer_columns(cls):
         if isinstance(existing, Transient):
             continue
 
-        # 推断默认值：非 None 的类属性值作为 Column default
-        default_val = None
+        # 只有显式赋值才给默认值；无赋值则仅创建 Column() 记录类型
         if existing is not None and not callable(existing) \
                 and not isinstance(existing, (classmethod, staticmethod)):
-            default_val = existing
+            col = Column(default=existing)
+        else:
+            col = Column()
 
-        # 创建 Column 描述符并挂到类上
-        setattr(cls, attr_name, Column(default=default_val))
+        setattr(cls, attr_name, col)
 
 
 def _auto_generate_init(cls):

{springbootai-2.2.3 → springbootai-2.2.5}/spring/orm/pymybatis/annotations/__init__.py

@@ -16,6 +16,7 @@ from .annotations import (
     Result,
     ResultMap,
     Select,
+    SelectPage,
     SelectProvider,
     Transactional,
     Update,
@@ -23,7 +24,7 @@ from .annotations import (
 )
 
 __all__ = [
-    'Select', 'Insert', 'Update', 'Delete',
+    'Select', 'SelectPage', 'Insert', 'Update', 'Delete',
     'SelectProvider', 'InsertProvider', 'UpdateProvider', 'DeleteProvider',
     'ResultMap', 'Result',
     'Options', 'Param', 'CacheNamespace', 'DataSource', 'Transactional',

{springbootai-2.2.3 → springbootai-2.2.5}/spring/orm/pymybatis/annotations/annotations.py

@@ -55,6 +55,67 @@ def Select(value: str, result_map: Optional[str] = None,
     return decorator
 
 
+class SelectPageAnnotation:
+    """
+    分页查询注解数据对象
+
+    用于标注Mapper方法，自动执行分页查询（COUNT + LIMIT/OFFSET）。
+    方法参数中名为 ``page_num`` 和 ``page_size`` 的参数会自动提取为分页参数，
+    其余参数作为SQL绑定参数。
+    """
+
+    def __init__(self, value: str, count_sql: Optional[str] = None,
+                 result_map: Optional[str] = None,
+                 result_type: Optional[str] = None,
+                 fetch_size: Optional[int] = None,
+                 timeout: Optional[int] = None):
+        self.value = value
+        self.count_sql = count_sql
+        self.result_map = result_map
+        self.result_type = result_type
+        self.fetch_size = fetch_size
+        self.timeout = timeout
+
+
+def SelectPage(value: str, count_sql: Optional[str] = None,
+               result_map: Optional[str] = None,
+               result_type: Optional[str] = None,
+               fetch_size: Optional[int] = None,
+               timeout: Optional[int] = None) -> Callable:
+    """
+    分页查询注解装饰器
+
+    用于标注Mapper接口方法，自动执行分页查询。
+    框架会从方法参数中提取 ``page_num`` 和 ``page_size``（按参数名匹配），
+    其余参数作为SQL绑定参数。
+
+    Args:
+        value: 查询SQL语句（不含LIMIT/OFFSET，框架自动追加）
+        count_sql: 自定义COUNT语句，为空时框架自动包裹生成
+        result_map: 结果映射ID
+        result_type: 结果类型
+        fetch_size: 抓取大小
+        timeout: 超时时间（秒）
+
+    Returns:
+        装饰器函数
+
+    用法::
+
+        @SelectPage("SELECT id, name FROM users WHERE age > #{age}")
+        def find_page(self, age: int, page_num: int, page_size: int):
+            pass
+
+        # 返回: {"total": 100, "page_num": 1, "page_size": 10, "data": [...]}
+    """
+    def decorator(func: Callable) -> Callable:
+        annotation = SelectPageAnnotation(value, count_sql, result_map,
+                                          result_type, fetch_size, timeout)
+        setattr(func, 'select_page', annotation)
+        return func
+    return decorator
+
+
 class InsertAnnotation:
     """
     INSERT插入注解数据对象

{springbootai-2.2.3 → springbootai-2.2.5}/spring/orm/pymybatis/mapper/mapper.py

@@ -89,6 +89,7 @@ class MapperProxy:
         
         # 获取方法注解（通过装饰器附加的属性）
         select_annotation = getattr(wrapped_method, 'select', None)
+        select_page_annotation = getattr(wrapped_method, 'select_page', None)
         insert_annotation = getattr(wrapped_method, 'insert', None)
         update_annotation = getattr(wrapped_method, 'update', None)
         delete_annotation = getattr(wrapped_method, 'delete', None)
@@ -110,6 +111,29 @@ class MapperProxy:
             if options and options.flush_cache:
                 self.sql_session.sql_cache.clear()
 
+            # ── 分页查询 @SelectPage ──
+            if select_page_annotation:
+                page_num, page_size, sql_params = self._extract_pagination_params(
+                    method, params
+                )
+                result = self.sql_session.select_pagination(
+                    select_page_annotation.value,
+                    sql_params,
+                    page_num=page_num,
+                    page_size=page_size,
+                )
+                # 如果指定了 result_type，对 data 逐行转换
+                result_type = (
+                    select_page_annotation.result_type
+                    or self._result_type_from_return_annotation(method)
+                )
+                if result_type and result.get('data'):
+                    result['data'] = [
+                        self._apply_result_type(row, result_type)
+                        for row in result['data']
+                    ]
+                return result
+
             if select_annotation or select_provider:
                 provider_options = select_provider.options if select_provider else {}
                 select_sql = (
@@ -360,6 +384,49 @@ class MapperProxy:
             or method_name == 'find_one'
         )
 
+    @staticmethod
+    def _extract_pagination_params(method, params: Dict[str, Any]):
+        """
+        从方法参数中提取分页参数 page_num / page_size。
+
+        按参数名匹配（支持 Param 别名），提取后从 SQL 参数字典中移除，
+        避免它们被当作 SQL 绑定参数。
+
+        Returns:
+            (page_num, page_size, sql_params)
+        """
+        page_num = 1
+        page_size = 10
+        sql_params = {}
+
+        try:
+            sig = inspect.signature(method)
+        except (ValueError, TypeError):
+            sig = None
+
+        # 构建 参数名 → Param别名 映射
+        param_names: Dict[str, str] = {}
+        if sig is not None:
+            for pname, p in sig.parameters.items():
+                if pname == 'self':
+                    continue
+                alias = MapperProxy._parameter_alias(p.annotation, pname)
+                param_names[pname] = alias
+
+        for key, value in params.items():
+            if key == 'self':
+                continue
+            # 检查原始参数名和别名是否为分页参数
+            matched_name = param_names.get(key, key)
+            if matched_name in ('page_num', 'pageNum', 'page'):
+                page_num = int(value) if value is not None else 1
+            elif matched_name in ('page_size', 'pageSize', 'size'):
+                page_size = int(value) if value is not None else 10
+            else:
+                sql_params[key] = value
+
+        return page_num, page_size, sql_params
+
     @staticmethod
     def _is_collection_type(annotation: Any) -> bool:
         return get_origin(annotation) in {list, tuple, set, dict} or annotation in {

{springbootai-2.2.3 → springbootai-2.2.5}/spring/orm/pymybatis/version.py

@@ -2,7 +2,7 @@
 PyMyBatis版本信息
 """
 
-__version__ = '2.2.3'
+__version__ = '2.2.5'
 __author__ = 'PyMyBatis Team'
 __email__ = 'dev@pymybatis.org'
 __license__ = 'MIT'