后端开发

相关源文件

• .devcontainer/Dockerfile
• .devcontainer/README.md
• .devcontainer/devcontainer.json
• .devcontainer/noop.txt
• .devcontainer/post_create_command.sh
• .devcontainer/post_start_command.sh
• .devcontainer/troubleshooting.png
• .github/actions/setup-uv/action.yml
• .github/workflows/api-tests.yml
• .github/workflows/db-migration-test.yml
• .github/workflows/docker-build.yml
• .github/workflows/style.yml
• .github/workflows/vdb-tests.yml
• api/Dockerfile
• api/README.md
• api/constants/recommended_apps.json
• api/controllers/console/app/app.py
• api/controllers/console/app/site.py
• api/controllers/console/app/workflow.py
• api/docker/entrypoint.sh
• api/events/app_event.py
• api/events/event_handlers/__init__.py
• api/events/event_handlers/delete_tool_parameters_cache_when_sync_draft_workflow.py
• api/fields/app_fields.py
• api/fields/workflow_fields.py
• api/migrations/README
• api/migrations/versions/2025_03_03_1436-ee79d9b1c156_add_marked_name_and_marked_comment_in_.py
• api/migrations/versions/5fda94355fce_custom_disclaimer.py
• api/migrations/versions/b2602e131636_add_workflow_run_id_index_for_message.py
• api/services/app_dsl_service.py
• api/services/app_service.py
• api/services/errors/workflow_service.py
• api/services/recommended_app_service.py
• api/tests/unit_tests/services/workflow/test_workflow_service.py
• dev/pytest/pytest_vdb.sh
• dev/reformat
• web/.husky/pre-commit
• web/Dockerfile
• web/README.md
• web/app/(commonLayout)/apps/AppCard.tsx/apps/AppCard.tsx)
• web/app/(commonLayout)/apps/NewAppCard.tsx/apps/NewAppCard.tsx)
• web/app/(commonLayout)/datasets/DatasetFooter.tsx/datasets/DatasetFooter.tsx)
• web/app/components/app/duplicate-modal/index.tsx
• web/app/components/app/switch-app-modal/index.tsx
• web/app/components/base/tag-management/index.tsx
• web/app/components/base/tag-management/selector.tsx
• web/app/components/base/tag-management/tag-item-editor.tsx
• web/app/components/base/tag-management/tag-remove-modal.tsx
• web/app/components/datasets/create/website/base/checkbox-with-label.tsx
• web/app/components/datasets/external-knowledge-base/create/KnowledgeBaseInfo.tsx
• web/app/components/datasets/rename-modal/index.tsx
• web/service/apps.ts
• web/types/app.ts

本文档涵盖了 Dify API 服务的后端开发，包括开发环境设置、架构模式以及构建和扩展 API 端点、服务和业务逻辑的实现指南。有关前端开发，请参阅 前端开发。有关模型提供商集成，请参阅 扩展模型提供商。

开发环境设置

先决条件和包管理

Dify 在 v1.3.0 中使用 uv 作为 Python 包管理器，取代了 Poetry。开发环境需要 Python 3.11+，并使用容器化的中间件堆栈。

本地开发设置

来源：api/README.md11-79 .devcontainer/post_create_command.sh1-14

基于 Docker 的开发

开发环境使用 Docker Compose 进行中间件服务，并支持 DevContainer 开发。

开发命令

来源：api/README.md76-78 .devcontainer/post_create_command.sh7-12

架构概述

Flask 应用结构

后端遵循分层架构，在 API 控制器、业务服务和数据模型之间有清晰的隔离。

核心目录结构

来源：api/controllers/console/app/app.py1-363 api/services/app_service.py29-398 api/services/app_dsl_service.py112-780

请求处理流程

身份验证和授权流程

来源：api/controllers/console/app/app.py88-114 api/services/app_service.py74-164

核心后端组件

API 控制器

控制器处理 HTTP 请求，并实现具有适当身份验证和验证的 RESTful 端点。

控制器实现模式

来源：api/controllers/console/app/app.py31-175 api/controllers/console/app/workflow.py41-417

服务层

服务包含业务逻辑，并协调控制器和模型之间的关系。

服务实现模式

来源：api/services/app_service.py29-398 api/services/app_dsl_service.py112-780

数据模型和字段

模型定义数据库模式和业务实体，并带有用于 API 响应的字段序列化器。

模型关系和序列化

来源：api/fields/app_fields.py49-184 api/fields/workflow_fields.py43-74

API 开发工作流程

创建新的端点

实现新 API 端点请遵循此模式。

标准控制器实现

来源：api/controllers/console/app/app.py88-114 api/controllers/console/app/site.py40-84

服务方法实现

服务实现示例

来源：api/services/app_service.py74-164 api/services/app_dsl_service.py116-317

数据库迁移工作流程

迁移管理

来源： api/migrations/versions/5fda94355fce_custom_disclaimer.py20-46 .github/workflows/db-migration-test.yml54-57

测试与质量保证

测试结构

测试与质量工具

来源： .github/workflows/api-tests.yml47-93 .github/workflows/style.yml48-61 dev/reformat8-18

事件系统

后端采用事件驱动的架构，以实现组件之间的松耦合

事件系统实现

来源： api/events/app_event.py1-14 api/events/event_handlers/__init__.py1-11 api/events/event_handlers/delete_tool_parameters_cache_when_sync_draft_workflow.py8-34