我想要重构bookshelf后端服务,将现有的多个功能(bookshelf\daily-lesson\加后续的语文数学游戏)融合到一个服务中。 主要目标 1. 调整架构为离线使用SQLLite,在线使用mysql, 2. 两套db的数据访问层语法得兼容,有对应的dao抽象层,不要各写一套,类似java的多态、策略工厂等方式 进行较优雅的设计。 3. sqllite要能和服务端mysql做数据同步(上传和拉取),服务端有全量,在线时可以选择下载到本地,这样用户可以把资源按服务端类似的结构打包到本地。 4. 书籍、音频、单词、图片等资源类基础数据可以做全局,数据要做用户维度隔离,同时做用户维度数据存储。 5. python为后端 做好目录模块划分和分层,按照py推荐的大型项目规范定义目录结构(类似java的 controller service dao component utils constants enums resources config data 等,仅供参考,按照python规范设计) 6. 本次计划重构后做agent 所以类似llm action tool_use function_calling memory sandbox 等这些也都要预留好目录结构和扩展空间。 7. 将现有的bookshelf资源整理为db数据存储到表结构中,方便读取、更新处理。 核心里程碑规划: 1. 整理数据,将原本bookshelf中静态资源json、audio、video、images等资源整理到mysql中( `neotao@47.93.149.248:13307` password:`Yishu@1230`) 2. 改造`D:\codes\MyProjects\easy-study\bookshelf` 新增 `backend-v1`和`frontend-v1`.将原有json静态资源的数据接口改为查询后端接口(db) 3. 改造时要注意将域名context前缀改成可配置,方便后续资源路径/域名迁移和本地下载后使用局域网路径等方式而不影响应用逻辑(一套接口抽象多套实现:v0版 静态json作为接口;v1:后端通过mysql提供数据;v2离线通过后端+sqlList提供数据) ## 小步里程碑 每步改完提交一次,确认后再做下一步。 1. 初始化项目:`bookshelf/backend-v1` 空服务,端口 8170。已完成。 2. 初始化脚手架:分层目录占位,仍不写业务。已完成。 3. 基础分层:配置、数据源策略和 dao 抽象。已完成。 4. 初始化 `frontend-v1`,使用序号 7 的前端端口 5170,只访问 8170。已完成。 5. context 前缀改成可配置。已完成。 6. 接口适配:v0 静态 json、v1 mysql、v2 sqlite。 7. 资源入库,以及 sqlite 与 mysql 的上传和拉取。 ## 说明 数据库口令只留在本任务说明里,不写入代码、配置或提交。现有 `bookshelf` 的 5120 / 8120 不动。基础分层已完成:默认 SQLite,连接策略按配置选择引擎,查询共用一套语句。目录已按「目录划分」收拢。绘本列表和阅读接口已接 v0 静态 JSON。v1 / v2 只留来源接缝,还没有导入。孩子端书架和阅读页在 frontend-v1。 ## 用户对话整理 `bookshelf/backend-v1/README.md` 现在的目录:接口 `api`,业务 `service`,数据访问 `dao`,连接、同步、资源定位 `component`,配置、常量、枚举、工具各自一包,`resources` 放 SQL,本地库在项目下 `data`。`agent` 下预留 `llm`、`action`、`tool_use`、`function_calling`、`memory`、`sandbox`。问:在 python agent 项目中,有没有比这种目录结构设计更好的划分方式。 Python 有没有类似 MyBatis 的框架,把代码逻辑和 SQL 解开,后续改 SQL 时不必改到业务代码里。 我是资深 Java 开发,本来较倾向于 Java,但是由于 agent 生态更倾向于 TS 和 Python,所以不得已使用 Python。Java 有很多企业级开发的优秀经验可以借鉴到 Python 中,希望这个项目重构时在不过分强求向 Java 方向靠的同时适当借鉴 Java 的优秀设计,包括框架选择、解耦、分层、模块划分等。 ## 目录划分 配置和数据源已经按 SQLAlchemy 落地。空目录先不改。领域包和 agent 仍按下面收。 业务按领域包,层放在包内:`books`、`lessons`、`games` 各自放 `api.py`、`service.py`、`repository.py`。HTTP 和 agent 都调同一个 service。 双库策略只放在 `db/engine.py`。查询写一套。真正分叉的语句(upsert、JSON)收进 `db/dialect.py`。同步单独放 `db/sync/`。资源路径和 context 前缀放 `storage/`。用户隔离放 `identity/`。 `agent` 按运行时职责留四个位:`runtime.py`(一轮:模型、工具、观察)、`providers/`(模型协议,各家报文字段放适配器里)、`tools/`(把书、课、游戏注册成工具)、`memory/`(会话和长期记忆)。孩子侧允许做什么放 `policy.py`。`sandbox` 先不占顶层,只有某个工具要跑生成出来的代码时,再作为该工具的执行器。 `action`、`tool_use`、`function_calling` 合成 `tools/`。`llm` 改成 `providers/`。`component` 拆开,不再当杂项目录。`constants`、`enums`、`utils` 不作为顶层抽屉,跟到使用它们的领域包。 ## SQL 与代码 继续用已经接入的 SQLAlchemy 2,不引入 MyBatis 移植。普通查询写在领域仓储里,返回语句对象,service 只调用方法。SQLite 与 MySQL 仍共用这一套语句,由现有连接策略切换引擎。 和 MyBatis 同类、SQL 放在文件里的库是 aiosql(仍在发版)。pugsql 是同一思路。pybatis 名字最像,版本还在 0.1。这三份都要自己写 SQL 字符串,方言分叉时要各写一份,和「两套库不要各写一套」冲突,所以不作为主数据层。 某条 SQL 长、需要当 SQL 阅读和修改时,放到 `resources/sql/`,仓储用 SQLAlchemy `text()` 加载并绑定参数,仍然走现在的 Session。upsert、JSON 这类分叉语句留在 `db/dialect.py`。 ## 借鉴原则 借现在还站得住的 Java 做法:模块化单体、单向依赖、仓储边界、DTO 与表模型分开、变体用策略、事务放在业务边界。框架对应保持 FastAPI、Pydantic、SQLAlchemy 2,不换 Spring 式栈,也不加 MyBatis 移植。 每个领域包内部分层:`api.py`(HTTP)、`schemas.py`(入参出参)、`service.py`(用例和事务)、`repository.py`(语句,对外像 Mapper)、表模型放 `models.py` 或共享的 `db/models`。`api` 和 `agent/tools` 只调用 `service`。`service` 不依赖 FastAPI,也不自己创建 Engine。 接口只留给真有多种实现的点:已有的连接策略、资源来源 v0 json / v1 mysql / v2 sqlite、以后的模型 provider。普通 service 和 repository 直接写具体类型,不配 `IXxx` + `XxxImpl`,也不为 SQLite 和 MySQL 各写一套 DAO。 `utils`、`constants`、`enums`、`component` 不作为顶层抽屉。常量、枚举跟领域包。连接、同步、资源路径各自用 `db` 和 `storage` 这些有名字的包。