springbootAI 2.2.6__tar.gz → 2.3.1__tar.gz

{springbootai-2.2.6 → springbootai-2.3.1}/CHANGELOG.md

@@ -1,5 +1,54 @@
 # Changelog
 
+## [2.3.0] - 2026-08-15
+
+### 新增
+
+- **企业级注解驱动**：新增 10 个注解，将 16 项企业级功能改造为注解驱动模式。标记在 `@SpringBootApplication` 主类上即可启用，注解参数优先于配置文件。
+  - `@EnableOAuth2` — 启用 OAuth2 资源服务器（支持 HS256/RS256、issuer/audience/scope 校验）
+  - `@EnableCsrf` — 启用 CSRF 防护（Double Submit Cookie 模式）
+  - `@EnableDevTools` — 启用开发环境热重载（文件变更自动重启）
+  - `@EnableConfigServer` — 启用 Spring Cloud Config 配置中心客户端
+  - `@EnableBus` — 启用 Spring Cloud Bus 事件总线
+  - `@EnableBatchProcessing` — 启用 Spring Batch 批处理
+  - `@EnableDataRest` — 启用 Spring Data REST（自动暴露 Repository 为 CRUD API）
+  - `@BatchJob` / `@BatchStep` — 标记批处理作业和步骤
+  - `@RepositoryRestResource` — 标记 Repository 为 REST 资源
+- **OAuth2 资源服务器**：新增 `spring/security/oauth2.py`，支持 JWT Access Token 验证，HS256 对称密钥和 RS256 公钥（JWKS）两种算法。
+- **CSRF 防护**：新增 `spring/web/csrf.py`，实现 Double Submit Cookie 模式中间件。
+- **Kafka 支持**：新增 `spring/messaging/kafka.py`，提供 `KafkaClient`（生产者+消费者管理）和 `@KafkaListener`/`KafkaTemplate` 注解。
+- **DevTools 热重载**：新增 `spring/devtools.py`，提供 `FileWatcher`（轮询文件变更）和 `RestartTrigger`（静默期防抖）。
+- **数据库迁移完善**：新增 Undo 回滚迁移（U{version}__{desc}.sql）、迁移锁（MySQL/PostgreSQL/SQLite）、变量替换（${var}）、validate 校验方法。
+- **Actuator /heapdump 端点**：返回 tracemalloc 内存分配快照 + GC 统计（JSON 格式），对齐 Spring Boot /actuator/heapdump。
+- **配置元数据**：新增 `spring/config/spring-configuration-metadata.json`，IDE 可读取提供配置自动补全。
+- **项目脚手架**：新增 `spring/cli/scaffold.py`，支持 `springbootai init` 命令创建新项目。
+- **Spring CLI**：新增 `spring/cli/main.py`，提供 `springbootai` 统一命令入口（version/info/list/init/run/docs）。
+- **Starter 机制**：pyproject.toml 新增 `web`/`cloud`/`all` 组合 Starter extras。
+- **Spring Cloud Config**：新增 `spring/cloud/config_center.py`，支持 HTTP 和本地文件后端。
+- **Spring Cloud Bus**：新增 `spring/cloud/bus.py`，支持进程内和 MQ 后端事件总线。
+- **Spring Batch**：新增 `spring/batch/`，支持 Job/Step/Reader/Processor/Writer 组件。
+- **Spring Data REST**：新增 `spring/data/rest.py`，自动生成 Repository CRUD REST 端点。
+- **Spring HATEOAS**：新增 `spring/web/hateoas.py`，包含 Link/EntityModel/CollectionModel/PagedModel。
+- **Sphinx API 文档**：新增 `docs/conf.py` 和 `docs/index.rst`。
+
+### 测试
+
+- 新增 7 个测试文件，共 198 个测试用例：
+  - `test_kafka.py`（75）、`test_migration.py`（44）、`test_oauth2.py`（21）、`test_csrf.py`（19）、`test_devtools.py`（16）、`test_starter.py`（13）、`test_metadata.py`（10）
+- 新增 `test_new_annotations.py`（37 个注解测试）
+- 完整测试套件 **2821 passed, 11 skipped, 0 failed**
+
+### 文档
+
+- 新增 `doc/ENTERPRISE_ANNOTATIONS.md` — 10 个企业级注解完整教程
+- 新增 `doc/MIGRATION_MODULE.md` — 数据库迁移模块文档（10 章节）
+- 新增 `doc/STARTER_MODULE.md` — Starter 机制文档（8 章节）
+- 新增 `doc/CLI_MODULE.md` — CLI 和脚手架文档（10 章节）
+- `doc/MESSAGING_MODULE.md` 追加 Kafka 章节
+- `doc/WEB_MODULE.md` 追加 HATEOAS 章节
+- `doc/CONFIG_BINDING_MODULE.md` 追加配置元数据章节
+- 35 个文件版本号从 2.2.6 更新到 2.3.0
+
 ## [2.2.6] - 2026-08-15
 
 ### 新增

{springbootai-2.2.6/springbootAI.egg-info → springbootai-2.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: springbootAI
-Version: 2.2.6
+Version: 2.3.1
 Summary: Spring-style Python framework with Web, ORM, Cloud and AI integrations
 Author-email: YuConggen <1516933915@qq.com>
 License-Expression: MIT
@@ -45,6 +45,8 @@ Provides-Extra: redis
 Requires-Dist: redis==8.1.0; extra == "redis"
 Provides-Extra: rabbitmq
 Requires-Dist: pika==1.4.4; extra == "rabbitmq"
+Provides-Extra: kafka
+Requires-Dist: kafka-python==2.0.2; extra == "kafka"
 Provides-Extra: nacos
 Requires-Dist: nacos-sdk-python==2.0.11; extra == "nacos"
 Provides-Extra: prometheus
@@ -61,7 +63,7 @@ Requires-Dist: langchain-core==1.5.4; extra == "ai"
 Requires-Dist: langchain-classic==1.0.8; extra == "ai"
 Requires-Dist: langchain-text-splitters==1.1.2; extra == "ai"
 Requires-Dist: langchain-community==0.4.2; extra == "ai"
-Requires-Dist: numpy==2.2.6; extra == "ai"
+Requires-Dist: numpy==2.3.0; extra == "ai"
 Requires-Dist: pydantic==2.13.4; extra == "ai"
 Provides-Extra: langchain
 Requires-Dist: langchain-openai==1.4.2; extra == "langchain"
@@ -69,7 +71,7 @@ Requires-Dist: langchain-core==1.5.4; extra == "langchain"
 Requires-Dist: langchain-classic==1.0.8; extra == "langchain"
 Requires-Dist: langchain-text-splitters==1.1.2; extra == "langchain"
 Requires-Dist: langchain-community==0.4.2; extra == "langchain"
-Requires-Dist: numpy==2.2.6; extra == "langchain"
+Requires-Dist: numpy==2.3.0; extra == "langchain"
 Requires-Dist: pydantic==2.13.4; extra == "langchain"
 Requires-Dist: faiss-cpu<2,>=1.7.4; extra == "langchain"
 Requires-Dist: pypdf<6,>=4.0.0; extra == "langchain"
@@ -89,6 +91,32 @@ Requires-Dist: langgraph==1.2.9; extra == "langgraph"
 Requires-Dist: langgraph-checkpoint-sqlite==3.1.1; extra == "langgraph"
 Provides-Extra: mcp
 Requires-Dist: mcp==2.0.0; extra == "mcp"
+Provides-Extra: web
+Requires-Dist: fastapi==0.115.6; extra == "web"
+Requires-Dist: uvicorn==0.34.0; extra == "web"
+Requires-Dist: pydantic==2.13.4; extra == "web"
+Requires-Dist: python-multipart==0.0.20; extra == "web"
+Provides-Extra: cloud
+Requires-Dist: springbootAI[web]; extra == "cloud"
+Requires-Dist: springbootAI[redis]; extra == "cloud"
+Requires-Dist: springbootAI[rabbitmq]; extra == "cloud"
+Requires-Dist: springbootAI[kafka]; extra == "cloud"
+Requires-Dist: httpx==0.28.1; extra == "cloud"
+Provides-Extra: all
+Requires-Dist: springbootAI[web]; extra == "all"
+Requires-Dist: springbootAI[mysql]; extra == "all"
+Requires-Dist: springbootAI[redis]; extra == "all"
+Requires-Dist: springbootAI[rabbitmq]; extra == "all"
+Requires-Dist: springbootAI[kafka]; extra == "all"
+Requires-Dist: springbootAI[prometheus]; extra == "all"
+Requires-Dist: springbootAI[logging]; extra == "all"
+Requires-Dist: springbootAI[excel]; extra == "all"
+Requires-Dist: springbootAI[ai]; extra == "all"
+Requires-Dist: springbootAI[langchain]; extra == "all"
+Requires-Dist: springbootAI[langgraph]; extra == "all"
+Requires-Dist: springbootAI[mcp]; extra == "all"
+Requires-Dist: httpx==0.28.1; extra == "all"
+Requires-Dist: psutil==6.1.1; extra == "all"
 Provides-Extra: dev
 Requires-Dist: pytest==9.1.1; extra == "dev"
 Requires-Dist: pytest-cov==7.1.0; extra == "dev"
@@ -113,7 +141,7 @@ Requires-Dist: langchain-core==1.5.4; extra == "full"
 Requires-Dist: langchain-classic==1.0.8; extra == "full"
 Requires-Dist: langchain-text-splitters==1.1.2; extra == "full"
 Requires-Dist: langchain-community==0.4.2; extra == "full"
-Requires-Dist: numpy==2.2.6; extra == "full"
+Requires-Dist: numpy==2.3.0; extra == "full"
 Requires-Dist: pydantic==2.13.4; extra == "full"
 Requires-Dist: faiss-cpu<2,>=1.7.4; extra == "full"
 Requires-Dist: pypdf<6,>=4.0.0; extra == "full"
@@ -132,7 +160,7 @@ Requires-Dist: langgraph-checkpoint-sqlite==3.1.1; extra == "full"
 Requires-Dist: mcp==2.0.0; extra == "full"
 Dynamic: license-file
 
-# SpringBootAI
+# SpringBootAI
 
 <p align="center">
   <img src="doc/images/hero-banner.png" alt="SpringBootAI 功能总览" width="100%" />
@@ -155,7 +183,7 @@ SpringBootAI 是一个采用 Spring 风格注解和分层结构的 Python 应用
 | AI 与编排 | 模型调用、Tools、RAG、Chain、状态图、MCP client/server | LangChain / LangGraph / 官方 MCP SDK |
 | 生产治理 | 健康检查、Prometheus、限流熔断、追踪、Swagger | prometheus-client / OpenTelemetry / OpenAPI |
 
-当前版本是 `2.2.6`；支持 Python 3.10、3.11 和 3.12，许可证为 MIT。项目仍标记为 Beta。用于公网高并发、合规敏感或支付/订单/库存等核心系统前，必须完成目标数据库、流量模型、故障恢复和安全基线验证。内嵌 Gateway 适合内部路由，不替代公网 Nginx/Kong/WAF；Seata `distributed` 对接官方 TC + TCC 回调；`at` 模式通过 ORM 拦截器自动生成 undo_log 实现自动回滚。
+当前版本是 `2.3.0`；支持 Python 3.10、3.11 和 3.12，许可证为 MIT。项目仍标记为 Beta。用于公网高并发、合规敏感或支付/订单/库存等核心系统前，必须完成目标数据库、流量模型、故障恢复和安全基线验证。内嵌 Gateway 适合内部路由，不替代公网 Nginx/Kong/WAF；Seata `distributed` 对接官方 TC + TCC 回调；`at` 模式通过 ORM 拦截器自动生成 undo_log 实现自动回滚。
 
 [新手指南](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/BEGINNER_GUIDE.md) | [全部文档](https://github.com/YUCONGGEN/springbootAI/tree/master/doc) | [变更日志](https://github.com/YUCONGGEN/springbootAI/blob/master/CHANGELOG.md) | [安全报告](https://github.com/YUCONGGEN/springbootAI/blob/master/SECURITY.md) | [发布检查](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/RELEASE_CHECKLIST.md)
 
@@ -249,8 +277,11 @@ curl http://127.0.0.1:8080/api/hello/Alice
 | 模块 | 文档 | 安装方式 | 一句话说明 |
 |------|------|----------|-----------|
 | ✅ 新手入门 | [BEGINNER_GUIDE.md](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/BEGINNER_GUIDE.md) | 随核心包 | 从零安装、创建项目、运行接口、打开 Swagger |
+| ✅ Web MVC | [WEB_MODULE.md](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/WEB_MODULE.md) | 随核心包 | `@RestController` / 路由映射 / 参数绑定 / 跨域 / 全局异常处理 |
 | ✅ 常用注解模块 | [ANNOTATION_MODULES.md](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/ANNOTATION_MODULES.md) | 随核心包 | Bean Validation / 条件装配 / 缓存增强 / CSV / `@Version` / `@Transient` |
+| ✅ Bean 生命周期与增强 | [LIFECYCLE_MODULE.md](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/LIFECYCLE_MODULE.md) | 随核心包 | `@PostConstruct` / `@Slf4j` / `@Primary` / `@Profile` / `@AuditLog` / `@FeatureToggle` |
 | ✅ AOP / 后置鉴权 / 重试恢复 | [AOP_SECURITY_RETRY.md](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/AOP_SECURITY_RETRY.md) | 随核心包 | `@Aspect` 通知 / `@PostAuthorize` / `@Recover`，含小白示例与常见错误 |
+| ✅ 并发与弹性 | [CONCURRENCY_MODULE.md](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/CONCURRENCY_MODULE.md) | 随核心包 | `@Async` / `@Scheduled` / `@RateLimit` / `@CircuitBreaker` / `@Idempotent` / `@Lock` |
 | 📦 AI（对接大模型） | [AI_MODULE.md](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/AI_MODULE.md) | `pip install springbootAI[ai]` | ChatClient / Advisor / Tools / RAG / Function Calling / 多厂商适配 |
 | 📦 LangChain | [LANGCHAIN_MODULE.md](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/LANGCHAIN_MODULE.md) | `pip install springbootAI[langchain]` | Chains / Agents / Memory / Retrievers / VectorStores / 30+ 提供商 |
 | 📦 LangGraph | [LANGGRAPH_MODULE.md](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/LANGGRAPH_MODULE.md) | `pip install springbootAI[langgraph]` | 状态图 / 条件路由 / 人工中断 / 注解式工作流 |
@@ -258,6 +289,7 @@ curl http://127.0.0.1:8080/api/hello/Alice
 | ✅ 内嵌 PyMyBatis ORM | [ORM_MODULE.md](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/ORM_MODULE.md) | 随核心包 | Mapper 注解 / XML Mapper / 分页 / SQL 安全 / DDL 自动建表 / Repository 分页查询 |
 | ✅ 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 / 分布式事务 |
+| 📦 消息队列 | [MESSAGING_MODULE.md](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/MESSAGING_MODULE.md) | `pip install springbootAI[rabbitmq]` | `@RabbitListener` / `RabbitTemplate` RabbitMQ 消息收发 |
 | 📦 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 文档 |
@@ -270,6 +302,10 @@ curl http://127.0.0.1:8080/api/hello/Alice
 | ✅ ⑥ 测试切片 | [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) | 随核心包 | 像微信一样实时通信 |
+| ✅ 企业级注解驱动 | [ENTERPRISE_ANNOTATIONS.md](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/ENTERPRISE_ANNOTATIONS.md) | 随核心包 | `@EnableOAuth2`/`@EnableCsrf`/`@EnableDevTools`/`@EnableBatchProcessing` 等10个注解 |
+| ✅ 数据库迁移 | [MIGRATION_MODULE.md](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/MIGRATION_MODULE.md) | 随核心包 | Flyway风格版本化迁移/Undo回滚/迁移锁/变量替换 |
+| ✅ Starter机制 | [STARTER_MODULE.md](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/STARTER_MODULE.md) | 随核心包 | `pip install springbootAI[web/cloud/all]` 组合依赖 |
+| ✅ CLI与脚手架 | [CLI_MODULE.md](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/CLI_MODULE.md) | 随核心包 | `springbootai init/run/docs` 命令行工具 |
 | — 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) | — | 全量测试用例与覆盖范围 |
 
@@ -280,10 +316,11 @@ curl http://127.0.0.1:8080/api/hello/Alice
 ### 🎯 新手推荐阅读顺序
 
 1. 先按 [新手入门指南](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/BEGINNER_GUIDE.md) 跑通 `/api/hello/{name}`。
-2. 阅读本页第 4、6、7 章，理解配置、依赖注入和 Controller。
+2. 阅读本页第 4、6、7 章，理解配置、依赖注入和 Controller；深入学习 Web 注解看 [WEB_MODULE.md](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/WEB_MODULE.md)。
 3. 做数据库 CRUD 时阅读 [ORM_MODULE.md](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/ORM_MODULE.md)。
 4. 需要输入校验、缓存或条件开关时阅读 [ANNOTATION_MODULES.md](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/ANNOTATION_MODULES.md)。
-5. 最后再按业务需要选择安全、Cloud、AI、LangChain、Excel、WebSocket 等文档。
+5. 需要异步、定时任务、限流、熔断时阅读 [CONCURRENCY_MODULE.md](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/CONCURRENCY_MODULE.md)。
+6. 最后再按业务需要选择安全、Cloud、消息队列、AI、LangChain、Excel、WebSocket 等文档。
 
 ---
 
@@ -326,10 +363,10 @@ SpringBootAI 是一个 **Python Web 框架**。它把 Java Spring Boot 的"注
 
 | 组件 | 当前版本 |
 |------|----------|
-| `spring` 框架 API | 2.2.6 |
-| `spring.orm.pymybatis` | 2.2.6 |
-| `spring.ai` AI 模块 | 2.2.6 |
-| `spring.langchain` LangChain 模块 | 2.2.6 |
+| `spring` 框架 API | 2.3.0 |
+| `spring.orm.pymybatis` | 2.3.0 |
+| `spring.ai` AI 模块 | 2.3.0 |
+| `spring.langchain` LangChain 模块 | 2.3.0 |
 | Python | 3.10+ |
 
 ### 1.4 适合什么场景

{springbootai-2.2.6 → springbootai-2.3.1}/README.md

@@ -1,4 +1,4 @@
-# SpringBootAI
+# SpringBootAI
 
 <p align="center">
   <img src="doc/images/hero-banner.png" alt="SpringBootAI 功能总览" width="100%" />
@@ -21,7 +21,7 @@ SpringBootAI 是一个采用 Spring 风格注解和分层结构的 Python 应用
 | AI 与编排 | 模型调用、Tools、RAG、Chain、状态图、MCP client/server | LangChain / LangGraph / 官方 MCP SDK |
 | 生产治理 | 健康检查、Prometheus、限流熔断、追踪、Swagger | prometheus-client / OpenTelemetry / OpenAPI |
 
-当前版本是 `2.2.6`；支持 Python 3.10、3.11 和 3.12，许可证为 MIT。项目仍标记为 Beta。用于公网高并发、合规敏感或支付/订单/库存等核心系统前，必须完成目标数据库、流量模型、故障恢复和安全基线验证。内嵌 Gateway 适合内部路由，不替代公网 Nginx/Kong/WAF；Seata `distributed` 对接官方 TC + TCC 回调；`at` 模式通过 ORM 拦截器自动生成 undo_log 实现自动回滚。
+当前版本是 `2.3.0`；支持 Python 3.10、3.11 和 3.12，许可证为 MIT。项目仍标记为 Beta。用于公网高并发、合规敏感或支付/订单/库存等核心系统前，必须完成目标数据库、流量模型、故障恢复和安全基线验证。内嵌 Gateway 适合内部路由，不替代公网 Nginx/Kong/WAF；Seata `distributed` 对接官方 TC + TCC 回调；`at` 模式通过 ORM 拦截器自动生成 undo_log 实现自动回滚。
 
 [新手指南](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/BEGINNER_GUIDE.md) | [全部文档](https://github.com/YUCONGGEN/springbootAI/tree/master/doc) | [变更日志](https://github.com/YUCONGGEN/springbootAI/blob/master/CHANGELOG.md) | [安全报告](https://github.com/YUCONGGEN/springbootAI/blob/master/SECURITY.md) | [发布检查](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/RELEASE_CHECKLIST.md)
 
@@ -115,8 +115,11 @@ curl http://127.0.0.1:8080/api/hello/Alice
 | 模块 | 文档 | 安装方式 | 一句话说明 |
 |------|------|----------|-----------|
 | ✅ 新手入门 | [BEGINNER_GUIDE.md](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/BEGINNER_GUIDE.md) | 随核心包 | 从零安装、创建项目、运行接口、打开 Swagger |
+| ✅ Web MVC | [WEB_MODULE.md](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/WEB_MODULE.md) | 随核心包 | `@RestController` / 路由映射 / 参数绑定 / 跨域 / 全局异常处理 |
 | ✅ 常用注解模块 | [ANNOTATION_MODULES.md](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/ANNOTATION_MODULES.md) | 随核心包 | Bean Validation / 条件装配 / 缓存增强 / CSV / `@Version` / `@Transient` |
+| ✅ Bean 生命周期与增强 | [LIFECYCLE_MODULE.md](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/LIFECYCLE_MODULE.md) | 随核心包 | `@PostConstruct` / `@Slf4j` / `@Primary` / `@Profile` / `@AuditLog` / `@FeatureToggle` |
 | ✅ AOP / 后置鉴权 / 重试恢复 | [AOP_SECURITY_RETRY.md](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/AOP_SECURITY_RETRY.md) | 随核心包 | `@Aspect` 通知 / `@PostAuthorize` / `@Recover`，含小白示例与常见错误 |
+| ✅ 并发与弹性 | [CONCURRENCY_MODULE.md](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/CONCURRENCY_MODULE.md) | 随核心包 | `@Async` / `@Scheduled` / `@RateLimit` / `@CircuitBreaker` / `@Idempotent` / `@Lock` |
 | 📦 AI（对接大模型） | [AI_MODULE.md](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/AI_MODULE.md) | `pip install springbootAI[ai]` | ChatClient / Advisor / Tools / RAG / Function Calling / 多厂商适配 |
 | 📦 LangChain | [LANGCHAIN_MODULE.md](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/LANGCHAIN_MODULE.md) | `pip install springbootAI[langchain]` | Chains / Agents / Memory / Retrievers / VectorStores / 30+ 提供商 |
 | 📦 LangGraph | [LANGGRAPH_MODULE.md](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/LANGGRAPH_MODULE.md) | `pip install springbootAI[langgraph]` | 状态图 / 条件路由 / 人工中断 / 注解式工作流 |
@@ -124,6 +127,7 @@ curl http://127.0.0.1:8080/api/hello/Alice
 | ✅ 内嵌 PyMyBatis ORM | [ORM_MODULE.md](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/ORM_MODULE.md) | 随核心包 | Mapper 注解 / XML Mapper / 分页 / SQL 安全 / DDL 自动建表 / Repository 分页查询 |
 | ✅ 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 / 分布式事务 |
+| 📦 消息队列 | [MESSAGING_MODULE.md](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/MESSAGING_MODULE.md) | `pip install springbootAI[rabbitmq]` | `@RabbitListener` / `RabbitTemplate` RabbitMQ 消息收发 |
 | 📦 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 文档 |
@@ -136,6 +140,10 @@ curl http://127.0.0.1:8080/api/hello/Alice
 | ✅ ⑥ 测试切片 | [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) | 随核心包 | 像微信一样实时通信 |
+| ✅ 企业级注解驱动 | [ENTERPRISE_ANNOTATIONS.md](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/ENTERPRISE_ANNOTATIONS.md) | 随核心包 | `@EnableOAuth2`/`@EnableCsrf`/`@EnableDevTools`/`@EnableBatchProcessing` 等10个注解 |
+| ✅ 数据库迁移 | [MIGRATION_MODULE.md](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/MIGRATION_MODULE.md) | 随核心包 | Flyway风格版本化迁移/Undo回滚/迁移锁/变量替换 |
+| ✅ Starter机制 | [STARTER_MODULE.md](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/STARTER_MODULE.md) | 随核心包 | `pip install springbootAI[web/cloud/all]` 组合依赖 |
+| ✅ CLI与脚手架 | [CLI_MODULE.md](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/CLI_MODULE.md) | 随核心包 | `springbootai init/run/docs` 命令行工具 |
 | — 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) | — | 全量测试用例与覆盖范围 |
 
@@ -146,10 +154,11 @@ curl http://127.0.0.1:8080/api/hello/Alice
 ### 🎯 新手推荐阅读顺序
 
 1. 先按 [新手入门指南](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/BEGINNER_GUIDE.md) 跑通 `/api/hello/{name}`。
-2. 阅读本页第 4、6、7 章，理解配置、依赖注入和 Controller。
+2. 阅读本页第 4、6、7 章，理解配置、依赖注入和 Controller；深入学习 Web 注解看 [WEB_MODULE.md](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/WEB_MODULE.md)。
 3. 做数据库 CRUD 时阅读 [ORM_MODULE.md](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/ORM_MODULE.md)。
 4. 需要输入校验、缓存或条件开关时阅读 [ANNOTATION_MODULES.md](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/ANNOTATION_MODULES.md)。
-5. 最后再按业务需要选择安全、Cloud、AI、LangChain、Excel、WebSocket 等文档。
+5. 需要异步、定时任务、限流、熔断时阅读 [CONCURRENCY_MODULE.md](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/CONCURRENCY_MODULE.md)。
+6. 最后再按业务需要选择安全、Cloud、消息队列、AI、LangChain、Excel、WebSocket 等文档。
 
 ---
 
@@ -192,10 +201,10 @@ SpringBootAI 是一个 **Python Web 框架**。它把 Java Spring Boot 的"注
 
 | 组件 | 当前版本 |
 |------|----------|
-| `spring` 框架 API | 2.2.6 |
-| `spring.orm.pymybatis` | 2.2.6 |
-| `spring.ai` AI 模块 | 2.2.6 |
-| `spring.langchain` LangChain 模块 | 2.2.6 |
+| `spring` 框架 API | 2.3.0 |
+| `spring.orm.pymybatis` | 2.3.0 |
+| `spring.ai` AI 模块 | 2.3.0 |
+| `spring.langchain` LangChain 模块 | 2.3.0 |
 | Python | 3.10+ |
 
 ### 1.4 适合什么场景

{springbootai-2.2.6 → springbootai-2.3.1}/pyproject.toml

@@ -12,7 +12,7 @@ build-backend = "setuptools.build_meta"
 [project]
 # 发行名 springbootAI（PyPI 包名，pip install springbootAI）；导入包名仍为 spring
 name = "springbootAI"
-version = "2.2.6"
+version = "2.3.1"
 description = "Spring-style Python framework with Web, ORM, Cloud and AI integrations"
 readme = "README.md"
 license = "MIT"
@@ -71,6 +71,7 @@ redis = ["redis==8.1.0"]
 # 消息队列 - 类似 Spring Boot Starter AMQP
 # ========================================
 rabbitmq = ["pika==1.4.4"]
+kafka = ["kafka-python==2.0.2"]
 
 # ========================================
 # 服务发现 - 类似 Spring Cloud Alibaba Nacos
@@ -106,7 +107,7 @@ ai = [
     "langchain-classic==1.0.8",
     "langchain-text-splitters==1.1.2",
     "langchain-community==0.4.2",
-    "numpy==2.2.6",
+    "numpy==2.3.0",
     "pydantic==2.13.4",
 ]
 
@@ -122,7 +123,7 @@ langchain = [
     "langchain-classic==1.0.8",
     "langchain-text-splitters==1.1.2",
     "langchain-community==0.4.2",
-    "numpy==2.2.6",
+    "numpy==2.3.0",
     "pydantic==2.13.4",
     # 默认装上的向量库/文档/工具依赖（安全：全部锁定已知安全版本）
     "faiss-cpu>=1.7.4,<2",
@@ -158,6 +159,40 @@ mcp = [
     "mcp==2.0.0",
 ]
 
+# ========================================
+# 组合 Starter - 类似 Spring Boot Starter Web/Cloud/All
+# 安装：pip install springbootAI[web] / springbootAI[cloud] / springbootAI[all]
+# ========================================
+web = [
+    "fastapi==0.115.6",
+    "uvicorn==0.34.0",
+    "pydantic==2.13.4",
+    "python-multipart==0.0.20",
+]
+cloud = [
+    "springbootAI[web]",
+    "springbootAI[redis]",
+    "springbootAI[rabbitmq]",
+    "springbootAI[kafka]",
+    "httpx==0.28.1",
+]
+all = [
+    "springbootAI[web]",
+    "springbootAI[mysql]",
+    "springbootAI[redis]",
+    "springbootAI[rabbitmq]",
+    "springbootAI[kafka]",
+    "springbootAI[prometheus]",
+    "springbootAI[logging]",
+    "springbootAI[excel]",
+    "springbootAI[ai]",
+    "springbootAI[langchain]",
+    "springbootAI[langgraph]",
+    "springbootAI[mcp]",
+    "httpx==0.28.1",
+    "psutil==6.1.1",
+]
+
 # ========================================
 # 开发依赖
 # ========================================
@@ -196,7 +231,7 @@ full = [
     "langchain-classic==1.0.8",
     "langchain-text-splitters==1.1.2",
     "langchain-community==0.4.2",
-    "numpy==2.2.6",
+    "numpy==2.3.0",
     "pydantic==2.13.4",
     # LangChain 模块增强（对齐 springbootAI[langchain]）
     "faiss-cpu>=1.7.4,<2",
@@ -253,6 +288,9 @@ Issues = "https://github.com/YUCONGGEN/springbootAI/issues"
 
 [project.scripts]
 springbootai = "spring.main:run_cli"
+# 项目脚手架工具（类似 Spring Initializr），初始化符合 SpringBootAI 风格的新项目
+# 用法：springbootai-init my-project --modules web,orm
+springbootai-init = "spring.cli.scaffold:main"
 
 [tool.setuptools.packages.find]
 include = ["spring*"]

{springbootai-2.2.6 → springbootai-2.3.1}/requirements-ai.txt

@@ -30,6 +30,7 @@ langchain-text-splitters==1.1.2
 langchain-community==0.4.2
 
 # 向量相似度计算（cosine_similarity 等，未安装时降级内置 math.sqrt 实现）
+# 锁定 2.2.6 以保持 Python 3.10 兼容性（numpy 2.3+ 要求 Python >=3.11）
 numpy==2.2.6
 
 # 数据校验（pydantic v2，OutputParser 结构化输出依赖）

{springbootai-2.2.6 → springbootai-2.3.1}/spring/__init__.py

@@ -1,11 +1,11 @@
-from .annotations import *
+from .annotations import *
 from .context import *
 from .web import *
 from .config import *
 from .utils import *
 from .main import create_app, run, SpringApplication, run_cli
 
-__version__ = "2.2.6"
+__version__ = "2.3.1"
 __author__ = "yuconggen"
 __license__ = "MIT"
 

{springbootai-2.2.6 → springbootai-2.3.1}/spring/annotations/__init__.py

@@ -98,16 +98,22 @@ from .conditional import (
     ConditionalOnClass,
 )
 
-# 可选导入：消息队列注解（需要pika）
+# 可选导入：消息队列注解（RabbitMQ 需要 pika，Kafka 需要 kafka-python）
 try:
     from .messaging import (
         RabbitListener,
         RabbitTemplate,
+        KafkaListener,
+        KafkaTemplate,
+        kafka_template,
     )
 except ImportError:
-    # pika未安装，这些注解不可用
+    # 依赖未安装，这些注解不可用
     RabbitListener = None
     RabbitTemplate = None
+    KafkaListener = None
+    KafkaTemplate = None
+    kafka_template = None
 
 # Optional MCP annotations are dependency-safe until MCP is enabled.
 from spring.mcp.annotations import (
@@ -121,6 +127,24 @@ from spring.mcp.annotations import (
 from .langchain import LangChainCall, LangChainClient
 from .langgraph import GraphEdge, GraphInvoke, GraphNode, GraphRoute, LangGraph
 
+# 安全启用型注解（@EnableOAuth2 / @EnableCsrf）
+from .security import EnableOAuth2, EnableCsrf
+
+# 企业级启用型注解（@EnableDevTools / @EnableConfigServer / @EnableBus / @EnableBatchProcessing / @EnableDataRest）
+from .enterprise import (
+    EnableDevTools,
+    EnableConfigServer,
+    EnableBus,
+    EnableBatchProcessing,
+    EnableDataRest,
+)
+
+# 批处理注解（@BatchJob / @BatchStep）
+from .batch import BatchJob, BatchStep
+
+# 数据 REST 注解（@RepositoryRestResource）
+from .data import RepositoryRestResource
+
 __all__ = [
     "SpringBootApplication",
     "ComponentScan",
@@ -215,6 +239,9 @@ __all__ = [
     # 消息队列注解
     "RabbitListener",
     "RabbitTemplate",
+    "KafkaListener",
+    "KafkaTemplate",
+    "kafka_template",
     # Model Context Protocol
     "MCPCall",
     "MCPClient",
@@ -231,4 +258,18 @@ __all__ = [
     "GraphNode",
     "GraphRoute",
     "LangGraph",
+    # 安全启用型注解
+    "EnableOAuth2",
+    "EnableCsrf",
+    # 企业级启用型注解
+    "EnableDevTools",
+    "EnableConfigServer",
+    "EnableBus",
+    "EnableBatchProcessing",
+    "EnableDataRest",
+    # 批处理注解
+    "BatchJob",
+    "BatchStep",
+    # 数据 REST 注解
+    "RepositoryRestResource",
 ]

springbootai-2.3.1/spring/annotations/batch.py

@@ -0,0 +1,101 @@
+"""
+批处理注解
+
+提供 Spring Batch 风格的注解驱动批处理作业定义。
+
+使用示例::
+
+    @BatchJob(name="importUsers")
+    class ImportUserJob:
+        @BatchStep(name="readCsv", chunk_size=100)
+        def read_csv_step(self):
+            reader = CsvItemReader("users.csv")
+            processor = FunctionItemProcessor(lambda x: x)
+            writer = CsvItemWriter("output.csv")
+            return Step("readCsv", reader, processor, writer, chunk_size=100)
+
+对齐 Java Spring Batch：
+- Java 通过 @Job 和 @Step 注解定义批处理作业
+- Python 版本提供 @BatchJob 和 @BatchStep 注解标记作业和步骤
+"""
+from typing import Optional
+
+from .core import SpringAnnotation
+
+
+class BatchJob(SpringAnnotation):
+    """标记一个类为批处理作业
+
+    标记了此注解的类会被 BatchJobRegistry 注册，
+    可通过 JobLauncher 执行或通过 @EnableBatchProcessing(auto_run=True) 自动执行。
+
+    Attributes:
+        name: 作业名称（必须唯一）
+        description: 作业描述（可选）
+        restartable: 是否允许重启失败的作业（默认 True）
+
+    使用示例::
+
+        @BatchJob(name="importUsers", description="导入用户数据")
+        class ImportUserJob:
+            def execute(self, job_launcher):
+                # 定义并执行步骤
+                pass
+    """
+
+    _annotation_type = "batch_job"
+
+    def __init__(
+        self,
+        name: str,
+        description: str = '',
+        restartable: bool = True,
+    ):
+        super().__init__(
+            name=name,
+            description=description,
+            restartable=restartable,
+        )
+
+
+class BatchStep(SpringAnnotation):
+    """标记一个方法为批处理步骤
+
+    标记了此注解的方法应返回一个 Step 对象或 Step 配置。
+
+    Attributes:
+        name: 步骤名称
+        chunk_size: 分块大小（默认 10）
+        retry_limit: 最大重试次数（默认 0，不重试）
+        skip_limit: 最大跳过次数（默认 0，不跳过）
+
+    使用示例::
+
+        @BatchJob(name="dataPipeline")
+        class DataPipelineJob:
+            @BatchStep(name="extract", chunk_size=500)
+            def extract_step(self):
+                reader = CsvItemReader("input.csv")
+                writer = ListItemWriter()
+                return Step("extract", reader, None, writer, chunk_size=500)
+
+            @BatchStep(name="transform", chunk_size=100, retry_limit=3)
+            def transform_step(self):
+                ...
+    """
+
+    _annotation_type = "batch_step"
+
+    def __init__(
+        self,
+        name: str,
+        chunk_size: int = 10,
+        retry_limit: int = 0,
+        skip_limit: int = 0,
+    ):
+        super().__init__(
+            name=name,
+            chunk_size=chunk_size,
+            retry_limit=retry_limit,
+            skip_limit=skip_limit,
+        )

springbootai-2.3.1/spring/annotations/data.py

@@ -0,0 +1,67 @@
+"""
+数据 REST 注解
+
+提供 Spring Data REST 风格的注解，将 Repository 自动暴露为 REST API。
+
+使用示例::
+
+    @RepositoryRestResource(path="users")
+    class UserRepository(PagingAndSortingRepository):
+        entity_class = User
+        # ... CRUD 方法已由基类提供
+
+    # 应用启动时自动注册以下端点：
+    # GET    /api/users          列表（分页+排序）
+    # GET    /api/users/{id}     详情
+    # POST   /api/users          创建
+    # PUT    /api/users/{id}     更新
+    # DELETE /api/users/{id}     删除
+
+对齐 Java Spring Data REST：
+- Java 通过 @RepositoryRestResource 注解标记 Repository
+- Python 版本提供同名注解，配合 @EnableDataRest 使用
+"""
+from typing import Optional, Type
+
+from .core import SpringAnnotation
+
+
+class RepositoryRestResource(SpringAnnotation):
+    """标记 Repository 为可暴露的 REST 资源
+
+    标记了此注解的 Repository 类会在应用启动时
+    自动注册 CRUD REST 端点。
+
+    Attributes:
+        path: REST 路径（如 'users' → /api/users）
+        entity_class: 实体类（必须指定，用于创建实例和文档）
+        id_type: ID 字段类型（默认 int）
+        exported: 是否暴露为 REST（默认 True，设为 False 可临时禁用）
+
+    使用示例::
+
+        @RepositoryRestResource(path="users", entity_class=User)
+        class UserRestController:
+            def find_all(self, pageable):
+                ...
+
+        @RepositoryRestResource(path="orders", entity_class=Order, exported=False)
+        class OrderRepository:  # exported=False 时不注册 REST 端点
+            ...
+    """
+
+    _annotation_type = "repository_rest"
+
+    def __init__(
+        self,
+        path: str,
+        entity_class: Optional[Type] = None,
+        id_type: type = int,
+        exported: bool = True,
+    ):
+        super().__init__(
+            path=path,
+            entity_class=entity_class,
+            id_type=id_type,
+            exported=exported,
+        )