springbootAI 2.3.2__tar.gz → 2.3.3__tar.gz

{springbootai-2.3.2 → springbootai-2.3.3}/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## [2.3.3] - 2026-08-18
+
+### 测试补充与文档完善
+
+- 补充单元测试覆盖核心模块：新增 `test_core.py`（22个，覆盖 typing_utils/graceful_shutdown）、`test_retry.py`（29个，覆盖 Backoff/Retryable/@retry/recovery）、`test_scheduling.py`（18个，覆盖 cron解析/调度器）、`test_tracing.py`（17个，覆盖 LocalSpan/SkyWalkingTracer 降级）共86个测试用例
+- 文档中文化：将 `doc/LOMBOK_MODULE.md` 等英文文档完整翻译为中文
+- 安全加固：生产环境配置校验强化；取消 GitHub Actions 定时测试触发
+- 完整测试套件 2964+ 个测试通过
+
+## [2.3.2] - 2026-08-16
+
+### 文档与打包修正
+
+- 统一框架、文档和构建元数据版本；修正测试目录、可选依赖和生产 Profile 示例。
+
 ## [2.3.0] - 2026-08-15
 
 ### 新增
@@ -14,21 +29,21 @@
   - `@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`（静默期防抖）。
+- **OAuth2 资源服务器**：新增 `springbootai/security/oauth2.py`，支持 JWT Access Token 验证，HS256 对称密钥和 RS256 公钥（JWKS）两种算法。
+- **CSRF 防护**：新增 `springbootai/web/csrf.py`，实现 Double Submit Cookie 模式中间件。
+- **Kafka 支持**：新增 `springbootai/messaging/kafka.py`，提供 `KafkaClient`（生产者+消费者管理）和 `@KafkaListener`/`KafkaTemplate` 注解。
+- **DevTools 热重载**：新增 `springbootai/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）。
+- **配置元数据**：新增 `springbootai/config/spring-configuration-metadata.json`，IDE 可读取提供配置自动补全。
+- **项目脚手架**：新增 `springbootai/cli/scaffold.py`，支持 `springbootai init` 命令创建新项目。
+- **Spring CLI**：新增 `springbootai/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。
+- **Spring Cloud Config**：新增 `springbootai/cloud/config_center.py`，支持 HTTP 和本地文件后端。
+- **Spring Cloud Bus**：新增 `springbootai/cloud/bus.py`，支持进程内和 MQ 后端事件总线。
+- **Spring Batch**：新增 `springbootai/batch/`，支持 Job/Step/Reader/Processor/Writer 组件。
+- **Spring Data REST**：新增 `springbootai/data/rest.py`，自动生成 Repository CRUD REST 端点。
+- **Spring HATEOAS**：新增 `springbootai/web/hateoas.py`，包含 Link/EntityModel/CollectionModel/PagedModel。
 - **Sphinx API 文档**：新增 `docs/conf.py` 和 `docs/index.rst`。
 
 ### 测试
@@ -53,7 +68,7 @@
 
 ### 新增
 
-- **Seata AT 数据源代理**：新增 `spring/cloud/seata_at_proxy.py`（500 行），在 ORM 拦截器层自动记录 SQL 的 before/after image，生成 undo_log，全局事务回滚时自动反向恢复数据。支持 MySQL(`%s`) 和 SQLite(`?`) 占位符自动适配。Seata 模式从三模式（local/http/distributed）扩展为四模式（新增 `at`）。
+- **Seata AT 数据源代理**：新增 `springbootai/cloud/seata_at_proxy.py`（500 行），在 ORM 拦截器层自动记录 SQL 的 before/after image，生成 undo_log，全局事务回滚时自动反向恢复数据。支持 MySQL(`%s`) 和 SQLite(`?`) 占位符自动适配。Seata 模式从三模式（local/http/distributed）扩展为四模式（新增 `at`）。
 - **AT 代理测试**：新增 `tests/test_seata_at_proxy.py`（18 项全通过），覆盖 SQL 解析、undo_log CRUD、undo 反向恢复（INSERT→DELETE / UPDATE→UPDATE before / DELETE→INSERT before）、AT 拦截器记录、提交删除 undo_log。
 
 ### 重构
@@ -102,9 +117,12 @@
 ### 新增
 
 - ORM 实体字段自动推断：类型注解无需显式 `= Column(...)` 赋值，对齐 Java JPA 字段自动映射。
-  - `name: str` → 自动创建 `Column()`（无默认值，仅记录类型）
-  - `name: str = ""` → 自动创建 `Column(default="")`（赋值即为默认值）
-  - `name: int = 0` → 自动创建 `Column(default=0)`
+  -
+ame: str` → 自动创建 `Column()`（无默认值，仅记录类型）
+  -
+ame: str = ""` → 自动创建 `Column(default="")`（赋值即为默认值）
+  -
+ame: int = 0` → 自动创建 `Column(default=0)`
   - 已有 `Column()`/`Id()`/`CreateTime()` 等描述符的字段保留不覆盖
   - 以 `_` 开头的私有字段自动跳过
 
@@ -179,9 +197,9 @@
 
 ### 新增
 
-- 新增独立 `spring.langgraph` 模块，锁定 `langgraph==1.2.9`，提供状态图、条件路由、人工中断、恢复、流式调用和注解式工作流。
+- 新增独立 `springbootai.langgraph` 模块，锁定 `langgraph==1.2.9`，提供状态图、条件路由、人工中断、恢复、流式调用和注解式工作流。
 - 新增官方 SQLite checkpointer 安全工厂；关闭 pickle fallback、限制反序列化类型，并验证连接关闭后重新打开仍能恢复流程。
-- 新增 `spring.mcp` 客户端和服务端，基于官方 MCP Python SDK，支持 Tool、Resource、Prompt 及注解调用。
+- 新增 `springbootai.mcp` 客户端和服务端，基于官方 MCP Python SDK，支持 Tool、Resource、Prompt 及注解调用。
 - 新增 LangChain 和 LangGraph 注解 API；注解只负责声明，执行继续委托官方框架。
 - 压测新增 AI、LangChain、LangGraph、MCP workload，并纳入 9 小时 mixed 稳定性脚本。
 - CI 新增真实 MySQL、Redis、RabbitMQ、Nacos、Seata TCC 集成测试和依赖停机测试。

{springbootai-2.3.2 → springbootai-2.3.3}/MANIFEST.in

@@ -8,10 +8,10 @@ include requirements-langgraph.txt
 include requirements-mcp.txt
 include pyproject.toml
 
-graft spring
+graft springbootai
 graft sql
 
-# 排除开发/构建产物
+# 鎺掗櫎寮€鍙?鏋勫缓浜х墿
 global-exclude __pycache__
 global-exclude *.pyc
 global-exclude *.pyo

{springbootai-2.3.2/springbootAI.egg-info → springbootai-2.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: springbootAI
-Version: 2.3.2
+Version: 2.3.3
 Summary: Spring-style Python framework with Web, ORM, Cloud and AI integrations
 Author-email: YuConggen <1516933915@qq.com>
 License-Expression: MIT
@@ -63,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.3.0; extra == "ai"
+Requires-Dist: numpy==2.2.6; extra == "ai"
 Requires-Dist: pydantic==2.13.4; extra == "ai"
 Provides-Extra: langchain
 Requires-Dist: langchain-openai==1.4.2; extra == "langchain"
@@ -71,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.3.0; extra == "langchain"
+Requires-Dist: numpy==2.2.6; 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"
@@ -92,8 +92,8 @@ 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: fastapi==0.141.1; extra == "web"
+Requires-Dist: uvicorn==0.39.0; extra == "web"
 Requires-Dist: pydantic==2.13.4; extra == "web"
 Requires-Dist: python-multipart==0.0.20; extra == "web"
 Provides-Extra: cloud
@@ -141,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.3.0; extra == "full"
+Requires-Dist: numpy==2.2.6; 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"
@@ -183,7 +183,7 @@ SpringBootAI 是一个采用 Spring 风格注解和分层结构的 Python 应用
 | AI 与编排 | 模型调用、Tools、RAG、Chain、状态图、MCP client/server | LangChain / LangGraph / 官方 MCP SDK |
 | 生产治理 | 健康检查、Prometheus、限流熔断、追踪、Swagger | prometheus-client / OpenTelemetry / OpenAPI |
 
-当前版本是 `2.3.0`；支持 Python 3.10、3.11 和 3.12，许可证为 MIT。项目仍标记为 Beta。用于公网高并发、合规敏感或支付/订单/库存等核心系统前，必须完成目标数据库、流量模型、故障恢复和安全基线验证。内嵌 Gateway 适合内部路由，不替代公网 Nginx/Kong/WAF；Seata `distributed` 对接官方 TC + TCC 回调；`at` 模式通过 ORM 拦截器自动生成 undo_log 实现自动回滚。
+当前版本是 `2.3.2`；支持 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)
 
@@ -210,8 +210,8 @@ Linux/macOS 激活命令是 `source .venv/bin/activate`，其余 Python 命令
 创建 `demo/Application.py`：
 
 ```python
-from spring.annotations import SpringBootApplication
-from spring.main import run
+from springbootai.annotations import SpringBootApplication
+from springbootai.main import run
 
 
 @SpringBootApplication(scan_base_packages=["demo"])
@@ -226,8 +226,8 @@ if __name__ == "__main__":
 创建 `demo/controller/HelloController.py`：
 
 ```python
-from spring.annotations import GetMapping, RequestMapping, RestController
-from spring.web.swagger import Operation, Tag
+from springbootai.annotations import GetMapping, RequestMapping, RestController
+from springbootai.web.swagger import Operation, Tag
 
 
 @Tag(name="入门接口", description="确认应用已经正常运行")
@@ -288,10 +288,11 @@ curl http://127.0.0.1:8080/api/hello/Alice
 | 📦 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 自动建表 / Repository 分页查询 |
 | ✅ JPA 实体与仓库 | [JPA_MODULE.md](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/JPA_MODULE.md) | 随核心包 | `@Entity` + `@Table` / 字段自动推断 / `@CreateTime` / Repository / DataJpaTest |
+| ✅ Lombok 模型注解 | [LOMBOK_MODULE.md](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/LOMBOK_MODULE.md) | 随核心包 | `@Data` / `@Get` / `@Set` / `@ToString` 消除模型样板代码 |
 | ✅ 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` 注解驱动读写 |
+| ✅ CSV 读写 | [CSV_MODULE.md](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/CSV_MODULE.md) | 随核心包（Python 标准库 `csv`） | `@CsvProperty` / `@CsvIgnore` 注解驱动读写 |
 | ✅ Swagger 文档 | [SWAGGER_MODULE.md](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/SWAGGER_MODULE.md) | 随核心包 | `@Tag` / `@Operation` 注解驱动 API 文档 |
 | ✅ 安全 | [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` 属性复制工具 |
@@ -363,10 +364,10 @@ SpringBootAI 是一个 **Python Web 框架**。它把 Java Spring Boot 的"注
 
 | 组件 | 当前版本 |
 |------|----------|
-| `spring` 框架 API | 2.3.0 |
-| `spring.orm.pymybatis` | 2.3.0 |
-| `spring.ai` AI 模块 | 2.3.0 |
-| `spring.langchain` LangChain 模块 | 2.3.0 |
+| `springbootai` 框架 API | 2.3.2 |
+| `springbootai.orm.pymybatis` | 2.3.2 |
+| `springbootai.ai` AI 模块 | 2.3.2 |
+| `springbootai.langchain` LangChain 模块 | 2.3.2 |
 | Python | 3.10+ |
 
 ### 1.4 适合什么场景
@@ -464,7 +465,7 @@ python -m pip install springbootAI
 
 只有准备修改框架源码的贡献者，才需要先 `git clone`，进入仓库后执行 `python -m pip install -e .`。
 
-核心依赖包含 FastAPI、Uvicorn、PyYAML、python-dotenv、DBUtils、PyJWT、cryptography、bcrypt 和 Pydantic。**核心安装已包含内嵌 `spring.orm.pymybatis`，使用 Mapper 模式不需要再安装独立 `pymybatis`。**
+核心依赖包含 FastAPI、Uvicorn、PyYAML、python-dotenv、DBUtils、PyJWT、cryptography、bcrypt 和 Pydantic。**核心安装已包含内嵌 `springbootai.orm.pymybatis`，使用 Mapper 模式不需要再安装独立 `pymybatis`。**
 
 ### 3.3 可选 extras
 
@@ -484,7 +485,6 @@ python -m pip install "springbootAI[mcp]"
 ```bash
 python -m pip install -e ".[mysql]"             # PyMySQL
 python -m pip install -e ".[postgresql]"        # psycopg2-binary
-python -m pip install -e ".[oracle]"            # cx-Oracle
 python -m pip install -e ".[sqlalchemy]"        # SQLAlchemy 模式
 python -m pip install -e ".[redis]"             # Redis 能力
 python -m pip install -e ".[ast]"               # sqlglot AST 校验
@@ -516,8 +516,8 @@ pip install langchain-chroma         # Chroma 向量库
 ### 3.4 验证安装
 
 ```bash
-python -c "import spring; print(spring.__version__)"
-python -c "from spring.orm.pymybatis import __version__; print(__version__)"
+python -c "import springbootai; print(springbootai.__version__)"
+python -c "from springbootai.orm.pymybatis import __version__; print(__version__)"
 ```
 
 ### 3.5 最小应用
@@ -539,8 +539,8 @@ demo/
 创建 `demo/Application.py`：
 
 ```python
-from spring.annotations import SpringBootApplication
-from spring.main import run
+from springbootai.annotations import SpringBootApplication
+from springbootai.main import run
 
 
 @SpringBootApplication(scan_base_packages=["demo"])
@@ -555,7 +555,7 @@ if __name__ == "__main__":
 创建 `demo/controller/HelloController.py`：
 
 ```python
-from spring.annotations import GetMapping, RequestMapping, RestController
+from springbootai.annotations import GetMapping, RequestMapping, RestController
 
 
 @RequestMapping("/api")
@@ -614,7 +614,7 @@ curl http://127.0.0.1:8080/actuator/info
 
 ```python
 # asgi.py
-from spring.main import create_app
+from springbootai.main import create_app
 from demo.Application import Application
 
 app = create_app(Application)
@@ -685,7 +685,7 @@ database:
 ### 4.5 在代码里读配置
 
 ```python
-from spring.config import ConfigLoader
+from springbootai.config import ConfigLoader
 
 loader = ConfigLoader("./myapp/application.yml")
 port = loader.get("server.port", 8080)
@@ -698,7 +698,7 @@ snapshot = loader.get_config()
 ### 4.6 Profile 的真实行为
 
 ```python
-from spring.annotations import Profile, Service
+from springbootai.annotations import Profile, Service
 
 
 @Profile("dev")
@@ -760,7 +760,7 @@ Profile 用于 Bean 过滤和生产安全校验。多环境配置可使用以下
 | scan_base_packages | List[str] | None | 扫描的基础包路径 |
 
 ```python
-from spring.annotations import SpringBootApplication
+from springbootai.annotations import SpringBootApplication
 
 @SpringBootApplication(scan_base_packages=["com.example.service", "com.example.controller"])
 class Application:
@@ -774,7 +774,7 @@ class Application:
 #### @Component / @Service / @Repository
 
 ```python
-from spring.annotations import Component, Service, Repository
+from springbootai.annotations import Component, Service, Repository
 
 @Component
 class EmailUtil:
@@ -795,7 +795,7 @@ class UserRepository:
 #### @Autowired
 
 ```python
-from spring.annotations import Service, Autowired
+from springbootai.annotations import Service, Autowired
 
 @Service
 class UserService:
@@ -818,7 +818,7 @@ class UserService:
 `@RestController` 组合了 `@Controller` 和 `@ResponseBody`，返回值自动序列化为 JSON。
 
 ```python
-from spring.annotations import RestController, GetMapping
+from springbootai.annotations import RestController, GetMapping
 
 @RestController
 class UserController:
@@ -830,7 +830,7 @@ class UserController:
 #### @RequestMapping / @GetMapping / @PostMapping / @PutMapping / @PatchMapping / @DeleteMapping
 
 ```python
-from spring.annotations import RestController, GetMapping, PostMapping, PutMapping, PatchMapping, DeleteMapping
+from springbootai.annotations import RestController, GetMapping, PostMapping, PutMapping, PatchMapping, DeleteMapping
 
 @RestController
 class UserController:
@@ -858,9 +858,9 @@ class UserController:
 #### @ControllerAdvice / @ExceptionHandler
 
 ```python
-from spring.annotations import ControllerAdvice, ExceptionHandler
+from springbootai.annotations import ControllerAdvice, ExceptionHandler
 
-@ControllerAdvice
+@ControllerAdvice()
 class GlobalExceptionHandler:
     @ExceptionHandler(ValueError, TypeError)
     def handle_validation_error(self, e: Exception):
@@ -891,7 +891,7 @@ class GlobalExceptionHandler:
 ### 5.5 配置与属性注解
 
 ```python
-from spring.annotations import Configuration, Bean, Service, Value, ConfigurationProperties, Component
+from springbootai.annotations import Configuration, Bean, Service, Value, ConfigurationProperties, Component
 
 @Configuration
 class AppConfig:
@@ -906,7 +906,7 @@ class AppService:
         self.app_name = value
 
 @Component
-@ConfigurationProperties(prefix="spring.datasource")
+@ConfigurationProperties(prefix="springbootai.datasource")
 class DataSourceProperties:
     def __init__(self):
         self.url = ""
@@ -917,7 +917,7 @@ class DataSourceProperties:
 ### 5.6 日志与生命周期
 
 ```python
-from spring.annotations import Service, Slf4j, PostConstruct, PreDestroy
+from springbootai.annotations import Service, Slf4j, PostConstruct, PreDestroy
 
 @Service
 @Slf4j  # 自动创建 self.logger
@@ -941,8 +941,8 @@ class InitService:
 ### 5.7 应用事件
 
 ```python
-from spring.annotations import ApplicationEvent, Autowired, EventListener, Service
-from spring.event import ApplicationEventPublisher
+from springbootai.annotations import ApplicationEvent, Autowired, EventListener, Service
+from springbootai.event import ApplicationEventPublisher
 
 
 class UserCreatedEvent(ApplicationEvent):
@@ -975,7 +975,7 @@ class UserService:
 **解决什么问题**：限制接口被调用的频率，防止被刷爆。
 
 ```python
-from spring.annotations import RateLimit, Service
+from springbootai.annotations import RateLimit, Service
 
 @Service
 class OrderService:
@@ -995,7 +995,7 @@ class OrderService:
 **解决什么问题**：当某个方法持续失败时，暂时停止调用它（"熔断"），等一段时间后再试。
 
 ```python
-from spring.annotations import CircuitBreaker, Service
+from springbootai.annotations import CircuitBreaker, Service
 
 @Service
 class PaymentService:
@@ -1014,7 +1014,7 @@ class PaymentService:
 **解决什么问题**：用户手抖点了两次"下单"，保证只有一次生效。
 
 ```python
-from spring.annotations import Idempotent, Service
+from springbootai.annotations import Idempotent, Service
 
 @Service
 class OrderService:
@@ -1030,8 +1030,8 @@ class OrderService:
 ### 5.9 事务、缓存、任务与异步注解
 
 ```python
-from spring.annotations import Service, Transactional, Cacheable, Retryable, Async, Scheduled
-from spring.retry.retry_annotations import Backoff
+from springbootai.annotations import Service, Transactional, Cacheable, Retryable, Async, Scheduled
+from springbootai.retry.retry_annotations import Backoff
 
 @Service
 class OrderService:
@@ -1133,7 +1133,7 @@ def create(self, order_id: str, amount: float):
 ### 6.2 构造器注入（推荐方式）
 
 ```python
-from spring.annotations import Autowired, Service
+from springbootai.annotations import Autowired, Service
 
 
 @Service
@@ -1158,7 +1158,7 @@ class UserService:
 ### 6.4 配置类和 @Bean
 
 ```python
-from spring.annotations import Bean, Configuration
+from springbootai.annotations import Bean, Configuration
 
 
 @Configuration
@@ -1172,7 +1172,7 @@ class AppConfig:
 ### 6.5 生命周期
 
 ```python
-from spring.annotations import Component, PostConstruct, PreDestroy
+from springbootai.annotations import Component, PostConstruct, PreDestroy
 
 
 @Component
@@ -1201,7 +1201,7 @@ class ResourceHolder:
 ### 7.1 类和方法映射
 
 ```python
-from spring.annotations import (
+from springbootai.annotations import (
     DeleteMapping, GetMapping, PatchMapping, PostMapping, PutMapping,
     RequestMapping, RestController,
 )
@@ -1236,7 +1236,7 @@ class UserController:
 ### 7.2 统一返回值
 
 ```python
-from spring.web import Result
+from springbootai.web import Result
 
 return Result.success({"id": 1}, message="创建成功")
 return Result.bad_request("姓名不能为空")
@@ -1246,12 +1246,12 @@ return Result.not_found("用户不存在")
 ### 7.3 全局异常处理 & CORS & 拦截器
 
 ```python
-from spring.annotations import ControllerAdvice, ExceptionHandler, Component
-from spring.web import Result
-from spring.web.interceptor import HandlerInterceptor
+from springbootai.annotations import ControllerAdvice, ExceptionHandler, Component
+from springbootai.web import Result
+from springbootai.web.interceptor import HandlerInterceptor
 
 
-@ControllerAdvice
+@ControllerAdvice()
 class GlobalExceptionHandler:
     @ExceptionHandler(ValueError)
     def handle_value_error(self, error: ValueError):
@@ -1292,7 +1292,7 @@ server:
 ### 9.1 Service 事务
 
 ```python
-from spring.annotations import Autowired, Service, Transactional
+from springbootai.annotations import Autowired, Service, Transactional
 
 
 @Service
@@ -1354,7 +1354,7 @@ jwt:
 ### 10.2 access/refresh token
 
 ```python
-from spring.security.jwt_utils import JwtUtils, jwt_utils
+from springbootai.security.jwt_utils import JwtUtils, jwt_utils
 
 access = jwt_utils.generate_token({"sub": "user-1"})
 refresh = jwt_utils.generate_refresh_token({"sub": "user-1"})
@@ -1367,7 +1367,7 @@ new_access = jwt_utils.refresh_token(refresh)
 ### 10.3 方法权限
 
 ```python
-from spring.annotations import Authenticate, GetMapping, PreAuthorize, RequestMapping, RestController
+from springbootai.annotations import Authenticate, GetMapping, PreAuthorize, RequestMapping, RestController
 
 
 @RestController
@@ -1384,7 +1384,7 @@ class AdminController:
 
 ### 10.4 安全基线
 
-- `SPRING_PROFILES_ACTIVE=production` + `STARTUP_FAIL_FAST=true`
+- `SPRING_PROFILES_ACTIVE=prod` + `STARTUP_FAIL_FAST=true`
 - `JWT_SECRET_KEY` 使用至少 32 字符的随机密钥
 - `CORS_ALLOW_CREDENTIALS=true` 时不能用 `*` 来源
 - SQL 值始终使用 `#{name}` 参数绑定
@@ -1396,7 +1396,7 @@ class AdminController:
 ### 11.1 @Cacheable
 
 ```python
-from spring.annotations import Service, Cacheable
+from springbootai.annotations import Service, Cacheable
 
 @Service
 class UserService:
@@ -1410,8 +1410,8 @@ class UserService:
 ### 11.2 @Retryable
 
 ```python
-from spring.annotations import Retryable
-from spring.retry.retry_annotations import Backoff
+from springbootai.annotations import Retryable
+from springbootai.retry.retry_annotations import Backoff
 
 @Retryable(value=(ConnectionError,), max_retries=3, backoff=Backoff(delay=1000, multiplier=2.0))
 def call_remote(self):
@@ -1423,7 +1423,7 @@ def call_remote(self):
 重试耗尽后可以使用 `@Recover`：
 
 ```python
-from spring.annotations import Recover, Retryable
+from springbootai.annotations import Recover, Retryable
 
 @Retryable(value=(ConnectionError,), max_attempts=3, backoff=200)
 def call_remote(self, key):
@@ -1439,7 +1439,7 @@ def recover_remote(self, error, key):
 ### 11.3 @Async & @Scheduled
 
 ```python
-from spring.annotations import Service, Async, Scheduled
+from springbootai.annotations import Service, Async, Scheduled
 
 @Service
 class EmailService:
@@ -1480,14 +1480,14 @@ class CleanupJob:
 
 > 完整文档：[LANGCHAIN_MODULE.md](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/LANGCHAIN_MODULE.md)。安装：`pip install springbootAI[langchain]`。
 >
-> 封装 langchain classic 全套：Chains / Agents(6 种) / Memory / Retrievers / VectorStores / Parsers / Loaders + 30+ 提供商。双向适配器复用 `spring.ai` 的模型 Bean。
+> 封装 langchain classic 全套：Chains / Agents(6 种) / Memory / Retrievers / VectorStores / Parsers / Loaders + 30+ 提供商。双向适配器复用 `springbootai.ai` 的模型 Bean。
 
 **最小示例**（无需 API Key）：
 
 ```python
-from spring.context.registry import BeanRegistry
-from spring.ai.autoconfig import configure_ai
-from spring.langchain.autoconfig import configure_langchain
+from springbootai.context.registry import BeanRegistry
+from springbootai.ai.autoconfig import configure_ai
+from springbootai.langchain.autoconfig import configure_langchain
 
 registry = BeanRegistry()
 configure_ai(registry=registry)
@@ -1539,7 +1539,7 @@ print(chain.run_llm_chain("回答: {q}", q="你好"))
 **推荐构造器注入**：
 
 ```python
-from spring.annotations import Autowired, Service
+from springbootai.annotations import Autowired, Service
 
 @Service
 class UserService:
@@ -1575,7 +1575,7 @@ Python：
 ```python
 from dataclasses import dataclass
 from typing import Optional
-from spring.orm import Mapper, Param, Select
+from springbootai.orm import Mapper, Param, Select
 
 
 @dataclass
@@ -1596,7 +1596,7 @@ class UserMapper:
 | Java | SpringBootAI | 说明 |
 |---|---|---|
 | `@EnableDiscoveryClient` + Nacos | `@EnableDiscoveryClient` + `discovery` 配置 | 需部署 Nacos 并做集成测试 |
-| `@FeignClient` | 同名 + `spring.cloud.feign` | 不兼容 Java interface proxy |
+| `@FeignClient` | 同名 + `springbootai.cloud.feign` | 不兼容 Java interface proxy |
 | `@SentinelResource` | 同名 | 已内嵌引擎，无需 Dashboard |
 | JPA `hibernate.ddl-auto` | `@entity` + `ddl-auto` 配置 | 支持 create/update/validate/create-drop |
 
@@ -1664,7 +1664,7 @@ database:
 
 **生产启动**：
 ```bash
-export SPRING_PROFILES_ACTIVE=production
+export SPRING_PROFILES_ACTIVE=prod
 export JWT_SECRET_KEY="使用密钥管理系统注入至少32字符的随机值"
 export STARTUP_FAIL_FAST=true
 uvicorn myapp.asgi:app --host 0.0.0.0 --port 8080 --workers 4
@@ -1772,7 +1772,7 @@ python -m pytest -q tests
 
 ### 17.5 生产启动拒绝 JWT
 
-设置 `SPRING_PROFILES_ACTIVE=production`、`STARTUP_FAIL_FAST=true`、`JWT_SECRET_KEY=<至少32字符随机密钥>`。
+设置 `SPRING_PROFILES_ACTIVE=prod`、`STARTUP_FAIL_FAST=true`、`JWT_SECRET_KEY=<至少32字符随机密钥>`。
 
 ### 17.6 Nacos / PATCH / 配置同步排错
 
@@ -1961,7 +1961,7 @@ pip install springbootAI[langgraph]
 pip install -r requirements-langgraph.txt
 ```
 
-完整的小白入门、配置说明、`spring.ai` 模型复用、持久化 checkpointer、异步调用和测试命令请阅读 [LANGGRAPH_MODULE.md](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/LANGGRAPH_MODULE.md)。可选依赖已包含官方 SQLite checkpointer，适合本地单进程恢复测试；多 worker 生产环境必须注入共享数据库后端。无 LangGraph 依赖时保持 `spring.langgraph.enabled=false`，不会影响其他模块。
+完整的小白入门、配置说明、`springbootai.ai` 模型复用、持久化 checkpointer、异步调用和测试命令请阅读 [LANGGRAPH_MODULE.md](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/LANGGRAPH_MODULE.md)。可选依赖已包含官方 SQLite checkpointer，适合本地单进程恢复测试；多 worker 生产环境必须注入共享数据库后端。无 LangGraph 依赖时保持 `springbootai.langgraph.enabled=false`，不会影响其他模块。
 
 ## MCP 客户端与服务端