FastAPI后端实战Academic Figure Generator服务层代码架构与实现原理【免费下载链接】academic-figure-generatorAI 驱动的学术论文配图生成平台。上传论文 → AI 分析内容生成 Prompt → 一键生成高质量科研配图还有配套的skill可在主流agent中使用项目地址: https://gitcode.com/gh_mirrors/ac/academic-figure-generatorAcademic Figure Generator 是一个 AI 驱动的学术论文配图生成平台其FastAPI 后端服务层实现了上传论文 → AI 分析生成 Prompt → 一键生成科研配图的完整链路。本文带你快速看懂这个 FastAPI 后端的分层架构、依赖注入设计和六大核心服务的实现原理帮你掌握一套可直接借鉴的工程实践。一、项目整体架构一图看懂 FastAPI 后端分层整个后端代码位于 backend/app/ 目录下采用经典的四层结构层级目录职责路由层backend/app/api/v1/定义 REST API 接口projects、documents、prompts、images 等服务层backend/app/services/核心业务逻辑本文重点模型层backend/app/models/SQLAlchemy ORM 模型SQLite配置层backend/app/config.py环境变量与全局配置请求的处理路径非常清晰路由层只做参数校验和结果返回真正的重活全部交给服务层完成。这种薄路由、厚服务的设计是 FastAPI 后端开发的最佳实践之一。二、配置与依赖注入FastAPI 后端的地基1. 集中式配置管理backend/app/config.py 基于pydantic-settings实现了一个Settings类把 API Key、数据库路径、上传大小限制等全部收敛到一处并支持从.env文件自动加载。通过lru_cache装饰的get_settings()保证全局单例任何服务都可以安全地读取配置。2. 数据库会话注入backend/app/dependencies.py 是理解整个服务层的关键。它做了三件事创建异步数据库引擎SQLite aiosqlite封装get_db依赖每个请求获得一个独立的异步会话成功自动提交、异常自动回滚提供get_async_session_factory()供 FastAPI 依赖注入之外的场景如启动任务复用这意味着所有服务层代码都只需要在构造函数里接收一个db参数无需关心连接的创建和释放——这正是 FastAPI 依赖注入的精髓。三、服务层services六大核心服务解析服务层是 Academic Figure Generator 的大脑backend/app/services/ 目录下共有六个服务各司其职1. document_service.py论文解析服务这是入口级服务负责把用户上传的论文变成结构化文本。它的亮点在于三重文件校验扩展名白名单 → 文件大小上限 → 魔数Magic Bytes二进制校验杜绝伪造文件PDF 智能分段使用 PyMuPDF 提取每段文字的字号通过正文字号 1pt的启发式规则自动识别标题还原论文章节结构统一解析入口parse()方法按文件类型路由到 PDF/DOCX/TXT 三个解析器失败时统一抛出业务异常源码见 backend/app/services/document_service.py。2. claude_code_service.pyAI Prompt 生成服务接入 Claude Agent SDK把解析好的论文章节喂给 AI让它分析内容并输出配图描述Prompt。服务层在这里只做编排组装输入、调用 SDK、解析输出、写入数据库AI 调用的细节被完整封装。3. image_service.py图片生成服务backend/app/services/image_service.py 对接 NanoBananaOpenAI 兼容格式图片 API。三个精心设计的映射表值得新手学习映射表作用RESOLUTION_MAP1K/2K/4K 分辨率档位 → 具体像素ASPECT_RATIO_MAP16:9、4:3、1:1 等比例 → 宽高比参数TIMEOUT_MAP分辨率越高API 超时时间越长最长 20 分钟生成结果以 base64 返回再由存储服务落盘。4. local_storage_service.py本地存储服务个人本地版的亮点设计——用本地文件系统替代了云端对象存储。backend/app/services/local_storage_service.py 维护uploads/上传论文和figures/生成图片两个目录提供保存、读取、删除、存在性检查四个原子操作上层代码通过相对路径访问文件天然支持迁移。5. prompt_service.pyPrompt 管理服务典型的构造注入风格PromptService(db)接收数据库会话提供按项目查询、单条获取、人工编辑、批量创建等 CRUD 方法。所有查询都基于 SQLAlchemy 的select()语句式 API异步执行。6. ocr_service.pyOCR 服务对图片类素材做文字识别辅助 AI 理解论文中的图表内容补齐纯文本解析的盲区。四、统一异常处理FastAPI 错误响应的工程化设计backend/app/core/exceptions.py 定义了一套异常体系这是很多新手项目最容易忽略的细节AppException基类携带status_code、detail、error_code三元组业务子类NotFoundException(404)、BadRequestException(400)、FileValidationException(422)、ExternalAPIException(502) 等统一处理器所有业务异常最终都转换成{error: 错误码, detail: 说明}的标准 JSON 响应服务层代码里只管raise NotFoundException(...)前端收到的永远是一致的错误格式——把怎么处理错误和在哪里出错误彻底解耦。五、应用启动流程main.py 的生命周期管理backend/app/main.py 采用 FastAPI 推荐的应用工厂 lifespan模式lifespan上下文管理器启动时自动创建 SQLite 表、幂等地写入 50 预设学术配色方案含色盲友好方案、确保数据目录存在create_app()工厂函数注册中间件CORS、请求日志、异常处理器、全部路由并把data/目录挂载为静态文件让生成的配图可以直接被浏览器访问路由动态注册_include_routers()通过importlib逐个加载路由模块单个路由导入失败只记录警告、不影响其他功能提升了启动的容错性。六、总结这套 FastAPI 架构的 3 个可借鉴点回顾整个服务层设计对新手最有价值的经验是薄路由 厚服务API 层不写业务逻辑所有能力沉淀为可复用的 Service 类依赖注入贯穿始终数据库会话、配置全部通过构造函数/依赖函数注入服务天然可测试、可替换异常即契约统一的异常基类 全局处理器让错误响应对前端保持稳定一致 想深入源码推荐按 backend/app/dependencies.py → backend/app/main.py → backend/app/services/ 的顺序阅读配合 docs/phase2-technical-design.md 的技术设计文档可以快速吃透整个 FastAPI 后端。【免费下载链接】academic-figure-generatorAI 驱动的学术论文配图生成平台。上传论文 → AI 分析内容生成 Prompt → 一键生成高质量科研配图还有配套的skill可在主流agent中使用项目地址: https://gitcode.com/gh_mirrors/ac/academic-figure-generator创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 FastAPI后端实战：Academic Figure Generator服务层代码架构与实现原理
FastAPI后端实战Academic Figure Generator服务层代码架构与实现原理【免费下载链接】academic-figure-generatorAI 驱动的学术论文配图生成平台。上传论文 → AI 分析内容生成 Prompt → 一键生成高质量科研配图还有配套的skill可在主流agent中使用项目地址: https://gitcode.com/gh_mirrors/ac/academic-figure-generatorAcademic Figure Generator 是一个 AI 驱动的学术论文配图生成平台其FastAPI 后端服务层实现了上传论文 → AI 分析生成 Prompt → 一键生成科研配图的完整链路。本文带你快速看懂这个 FastAPI 后端的分层架构、依赖注入设计和六大核心服务的实现原理帮你掌握一套可直接借鉴的工程实践。一、项目整体架构一图看懂 FastAPI 后端分层整个后端代码位于 backend/app/ 目录下采用经典的四层结构层级目录职责路由层backend/app/api/v1/定义 REST API 接口projects、documents、prompts、images 等服务层backend/app/services/核心业务逻辑本文重点模型层backend/app/models/SQLAlchemy ORM 模型SQLite配置层backend/app/config.py环境变量与全局配置请求的处理路径非常清晰路由层只做参数校验和结果返回真正的重活全部交给服务层完成。这种薄路由、厚服务的设计是 FastAPI 后端开发的最佳实践之一。二、配置与依赖注入FastAPI 后端的地基1. 集中式配置管理backend/app/config.py 基于pydantic-settings实现了一个Settings类把 API Key、数据库路径、上传大小限制等全部收敛到一处并支持从.env文件自动加载。通过lru_cache装饰的get_settings()保证全局单例任何服务都可以安全地读取配置。2. 数据库会话注入backend/app/dependencies.py 是理解整个服务层的关键。它做了三件事创建异步数据库引擎SQLite aiosqlite封装get_db依赖每个请求获得一个独立的异步会话成功自动提交、异常自动回滚提供get_async_session_factory()供 FastAPI 依赖注入之外的场景如启动任务复用这意味着所有服务层代码都只需要在构造函数里接收一个db参数无需关心连接的创建和释放——这正是 FastAPI 依赖注入的精髓。三、服务层services六大核心服务解析服务层是 Academic Figure Generator 的大脑backend/app/services/ 目录下共有六个服务各司其职1. document_service.py论文解析服务这是入口级服务负责把用户上传的论文变成结构化文本。它的亮点在于三重文件校验扩展名白名单 → 文件大小上限 → 魔数Magic Bytes二进制校验杜绝伪造文件PDF 智能分段使用 PyMuPDF 提取每段文字的字号通过正文字号 1pt的启发式规则自动识别标题还原论文章节结构统一解析入口parse()方法按文件类型路由到 PDF/DOCX/TXT 三个解析器失败时统一抛出业务异常源码见 backend/app/services/document_service.py。2. claude_code_service.pyAI Prompt 生成服务接入 Claude Agent SDK把解析好的论文章节喂给 AI让它分析内容并输出配图描述Prompt。服务层在这里只做编排组装输入、调用 SDK、解析输出、写入数据库AI 调用的细节被完整封装。3. image_service.py图片生成服务backend/app/services/image_service.py 对接 NanoBananaOpenAI 兼容格式图片 API。三个精心设计的映射表值得新手学习映射表作用RESOLUTION_MAP1K/2K/4K 分辨率档位 → 具体像素ASPECT_RATIO_MAP16:9、4:3、1:1 等比例 → 宽高比参数TIMEOUT_MAP分辨率越高API 超时时间越长最长 20 分钟生成结果以 base64 返回再由存储服务落盘。4. local_storage_service.py本地存储服务个人本地版的亮点设计——用本地文件系统替代了云端对象存储。backend/app/services/local_storage_service.py 维护uploads/上传论文和figures/生成图片两个目录提供保存、读取、删除、存在性检查四个原子操作上层代码通过相对路径访问文件天然支持迁移。5. prompt_service.pyPrompt 管理服务典型的构造注入风格PromptService(db)接收数据库会话提供按项目查询、单条获取、人工编辑、批量创建等 CRUD 方法。所有查询都基于 SQLAlchemy 的select()语句式 API异步执行。6. ocr_service.pyOCR 服务对图片类素材做文字识别辅助 AI 理解论文中的图表内容补齐纯文本解析的盲区。四、统一异常处理FastAPI 错误响应的工程化设计backend/app/core/exceptions.py 定义了一套异常体系这是很多新手项目最容易忽略的细节AppException基类携带status_code、detail、error_code三元组业务子类NotFoundException(404)、BadRequestException(400)、FileValidationException(422)、ExternalAPIException(502) 等统一处理器所有业务异常最终都转换成{error: 错误码, detail: 说明}的标准 JSON 响应服务层代码里只管raise NotFoundException(...)前端收到的永远是一致的错误格式——把怎么处理错误和在哪里出错误彻底解耦。五、应用启动流程main.py 的生命周期管理backend/app/main.py 采用 FastAPI 推荐的应用工厂 lifespan模式lifespan上下文管理器启动时自动创建 SQLite 表、幂等地写入 50 预设学术配色方案含色盲友好方案、确保数据目录存在create_app()工厂函数注册中间件CORS、请求日志、异常处理器、全部路由并把data/目录挂载为静态文件让生成的配图可以直接被浏览器访问路由动态注册_include_routers()通过importlib逐个加载路由模块单个路由导入失败只记录警告、不影响其他功能提升了启动的容错性。六、总结这套 FastAPI 架构的 3 个可借鉴点回顾整个服务层设计对新手最有价值的经验是薄路由 厚服务API 层不写业务逻辑所有能力沉淀为可复用的 Service 类依赖注入贯穿始终数据库会话、配置全部通过构造函数/依赖函数注入服务天然可测试、可替换异常即契约统一的异常基类 全局处理器让错误响应对前端保持稳定一致 想深入源码推荐按 backend/app/dependencies.py → backend/app/main.py → backend/app/services/ 的顺序阅读配合 docs/phase2-technical-design.md 的技术设计文档可以快速吃透整个 FastAPI 后端。【免费下载链接】academic-figure-generatorAI 驱动的学术论文配图生成平台。上传论文 → AI 分析内容生成 Prompt → 一键生成高质量科研配图还有配套的skill可在主流agent中使用项目地址: https://gitcode.com/gh_mirrors/ac/academic-figure-generator创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考