深入 Baserow 仓库目录结构从 backend、web-frontend 到 docs 的完整布局解析【免费下载链接】baserowBuild databases, automations, apps agents with AI — no code. Open source platform available on cloud and self-hosted. GDPR, HIPAA, SOC 2 compliant. Best Airtable alternative.项目地址: https://gitcode.com/GitHub_Trending/ba/baserow本篇以 Baserow 官方开发者文档 目录结构说明 为主体逐条解读仓库顶层布局与三大核心目录backend、web-frontend、docs的职责划分并结合仓库中的真实源码命令入口、路由注册、justfile 配方、测试 fixtures说明每个目录为什么这样组织、各配置项实际起什么作用帮助你在动手修改 Baserow 之前建立起一份可落地的仓库地图。一、单仓库Monorepo设计所有文件都在同一个仓库里文档开篇点明了 Baserow 的仓库组织哲学后端、前端、文档全部放在同一个仓库中。这样做有两个直接收益搭建 demo 和开发环境更简单——拉一个仓库就能同时开发前后端一次变更例如前后端联动的功能可以提交在同一个 merge request中避免跨仓库同步问题。从仓库根目录的实际结构看顶层包含的核心目录与文档描述一致并且还有若干仓库级文件根目录项作用backend/Python 后端Django整体被打进 backend 容器web-frontend/Nuxt 前端整体被打进 web-frontend 容器docs/开发者文档Markdowndocker-compose.yml、docker-compose.dev.yml生产/开发环境的编排文件.gitlab-ci.yml持续集成配置changelog.md 与 changelog/ 目录变更日志及其按版本组织的 JSON 条目.editorconfig编辑器统一格式配置justfile、dev.sh、Caddyfile.dev根级任务编排、开发脚本与开发用反向代理配置从源码结构看这个单仓库还包含文档未逐一展开的配套工程premium/、enterprise/两个后端/前端扩展包、e2e-tests/Playwright 端到端测试、embeddings/独立嵌入向量服务、formula/公式引擎 ANTLR 文法、integrations/、deploy/Helm/K8s/Cloudron 等部署方案。后端 justfile 中对PYTHONPATH的拼接直接印证了多包协作方式——它同时挂上了backend/src/、premium/backend/src/、enterprise/backend/src/三棵源码树见 backend/justfile 的_set_pythonpath变量说明开源主包与 premium/enterprise 扩展在同一 Python 工程中按插件形式共存。二、backendPython 后端的目录结构与工程工具文档说明backend目录只包含后端专属文件且整个目录会被加入 backend 容器镜像。2.1 顶层工程文件逐项解析pyproject.tomlPython 项目配置包含由uv管理的依赖声明。其中[project.scripts]段注册了命令行入口见 backend/pyproject.toml#L112-L113[project.scripts] baserow baserow.manage:mainuv.locklockfile保证依赖安装的可复现性。.flake8文档记载这是 flake8 的 linter 配置。结合仓库现状可以看到当前仓库的 lint 已经迁移到ruffbackend/justfile 的check配方执行ruff check --config pyproject.toml与ruff format --check并且检查范围覆盖backend/src/、premium/backend/src/、enterprise/backend/src/及各自的 tests 目录配方中的backend_source_dirs变量。baserow命令文件这其实是一个 Python 文件而非目录内容仅 5 行backend/baserow#!/usr/bin/env python from baserow.manage import main if __name__ __main__: main()它调用src/baserow源码目录下的manage.py中的main()并通过上面的pyproject.toml注册为可执行命令。因此当有人把 Baserow 作为依赖安装后直接运行baserow migrate就等价于python src/baserow/manage.py migrate。这是把 Django 项目封装成可分发包的典型做法。Dockerfile构建仅包含 backend 服务的基础镜像用--target dev构建则得到开发就绪dev ready镜像。justfileJust 任务文件覆盖安装依赖、lint、测试、开发服务器等场景。按 justfile 内的分组注释可以看到完整命令面1 - setupinit/install/code-runtime、2 - developmentrun-dev-server、run、manage、migrate、shell_plus、3 - testingtest、test-coverage、4 - code-qualitycheck/fix别名l/f、5 - productionrun-asgi、run-wsgi、run-celery*、6 - dependenciesjust uv args透传 uv 命令、7 - translations、8 - cici-test、ci-check-startup、check-migrations等。文件头部注释强调一个重要约束所有配方必须在 Docker 内与本地开发环境同样工作不得加入 docker 专属假设。pytest.ini运行测试时的 pytest 配置。2.2 src后端模块的完整源码backend/src目录包含 Baserow 后端模块的全部源码顶层子目录与文档描述的四个核心部分一一对应api通过 REST API 暴露 Baserow 的 Django 应用文档描述它是一个可选但默认安装、强烈推荐的 Django 应用内部按业务域划分目录每个目录各自维护 urls、views、serializers 和 errors。对照 backend/src/baserow/api 的实际结构可以看到workspaces/、applications/、user/、jobs/、search/、import_export/、integrations/、notifications/、trash/、snapshots/等业务目录以及被多处复用的通用模块serializers.py、errors.py、exceptions.py、decorators.py、mixins.py、pagination.py、registries.py等与文档每个部分有独立目录 若干通用模块的描述完全吻合。关于路由挂载文档说 urls.py 模块以api命名空间被根 url 配置包含这一点可以在 backend/src/baserow/config/urls.py#L20-L27 中得到验证urlpatterns ( [ re_path(r^api/, include(baserow.api.urls, namespaceapi)), path(_health/, old_deprecated_health_check, nameroot_health_check), ] plugin_registry.urls static(settings.MEDIA_URL_PATH, document_rootsettings.MEDIA_ROOT) )从源码结构看根路由还动态拼接了plugin_registry.urls插件贡献的路由与媒体静态文件路由这是文档未展开但理解 URL 布局时值得注意的细节。config基础设置、环境设置与根路由文档指出config包含基础设置、特定环境设置、根 url 配置和wsgi.py。当前 backend/src/baserow/config 目录下有settings/、urls.py、wsgi.py以及asgi.py、celery.py、db_routers.py、helpers.py。其中settings/按环境拆分base.py之外还有dev.py、test.py、e2e.py、heroku.py等与base 环境特定设置的描述一致。开发环境默认使用的设置模块是baserow.config.settings.dev见 backend/justfile 中django_settings变量。生产环境则通过 gunicorn 加载baserow.config.asgi:applicationci-check-startup配方或baserow.config.wsgi:applicationrun-wsgi配方。contrib可安装的可选应用文档说contrib存放可安装的额外应用目前只包含 database 插件的后端部分默认安装但可选。从仓库现状看backend/src/baserow/contrib 已经扩展为五个应用目录database/数据库引擎、automation/、builder/、dashboard/、integrations/Slack/Google/Outlook 等集成。这说明 contrib 的定位是按功能模块划分的可选 Django app 集合理解 Baserow 的功能开关机制时应从这里入手。core 与 manage.pycore必需且默认安装的 app包含贯穿整个后端的抽象概念以及 Baserow 核心的workspace 与 application概念代码此外还有可复用的 helper 类、函数和装饰器对应 backend/src/baserow/core。manage.py标准的 Django 管理命令入口位于 backend/src/baserow/manage.py也是前面提到的baserow命令文件最终调用的目标。另外src/baserow顶层还包含ws/WebSocket、throttling/、locale/i18n 翻译文件、actions.py、middleware.py、gunicorn.config.py等模块属于文档骨架之外的补充实现细节。2.3 tests镜像 src 的测试布局与 fixtures 体系文档说明backend/tests下有一个baserow目录目录结构与src/baserow一一对应只是存放的是测试而非源码测试文件一律以test_开头确保被 pytest 收集并以对应源文件的名称结尾。对照 backend/tests/baserow 可以看到core/、api/、contrib/、actions/、jobs/等与 src 同构的子目录验证了这套镜像约定。tests 目录下还有一个fixtures 目录其中包含带小助手方法的模块类用于快速构造测试数据。文档给出的经典用例是想在测试里快速造一个文本字段只需这样写def test_something_important(data_fixture): # A table, database and workspace have also been created because the text field depends # on them. field data_fixture.create_text_field()由于 text field 依赖 table、database 与 workspacefixture 会顺带把这三者一并创建出来测试代码因此保持极短。这一机制的落点可以在 backend/tests/baserow/core/fixtures 中找到。tests 顶层还有几个文档未细说的实用目录可辅助理解测试资产的组织方式backend/tests/conftest.pypytest 全局 fixture 入口backend/tests/test_data/CSV、PSD 等测试用数据文件backend/tests/airtable_responses/Airtable 导入功能的响应样例JSON、HTML 等backend/tests/templates/模板导入测试数据。三、web-frontendNuxt 前端的目录结构文档说明web-frontend目录只包含前端专属文件且整体被打进 web-frontend 容器。顶层文件与文档清单逐项对应如下括号内为仓库现状对照.babelrcbabel 编译器配置。.eslintignore/.eslintrc.jseslint 的忽略清单与配置。当前仓库中前端测试/构建体系已有 TypeScript 化痕迹web-frontend/tsconfig.json、web-frontend/jest.config.js 与 web-frontend/vitest.config.ts 并存eslint 主配置上移至根级 eslint.config.mjs。.prettierrcprettier 格式化配置。.stylelintrcstylelint 配置负责 lint scss 代码当前仓库中对应 web-frontend/stylelint.config.mjs。Dockerfile构建仅包含 web-frontend 服务的镜像同样支持--target dev构建开发就绪镜像。intellij-idea.webpack.config.js供 IntelliJ IDEA 使用的 webpack 配置为编辑器添加正确的别名web-frontend/intellij-idea.webpack.config.js。jest.config.jsJEST 测试运行配置。justfile安装依赖、运行 linter、运行测试的 Just 命令。nuxt.config.js文档记载为开发环境的 Nuxt 基础配置当前仓库中该文件已演进为 TypeScript 版本 web-frontend/nuxt.config.ts。package.json/yarn.lock主包配置与 yarn 自动生成的依赖锁文件web-frontend/package.json。3.1 config 子目录config目录包含若干基础 Nuxt 设置及针对不同环境的设置。文档举例在开发环境中会把 eslint loader 追加到 webpack 的 loader 链中使 lint 反馈直接进入开发服务器流程见 web-frontend/config。3.2 modules 子目录所有业务模块都遵循Nuxt 的通用目录结构组织路由、布局、组件、store 等约定。web-frontend/modules 下按功能划分了数百个模块目录这也是前端体量最大的部分。3.3 tests 子目录文档坦诚说明目前 web-frontend 的测试数量很少且由于测试未持续维护目录结构已经偏离约定——理想状态下 specs 应放在与之匹配的 modules 目录中。阅读 web-frontend/test 时应对此有预期它目前是一个集中存放测试的目录而非与 modules 同构的镜像。四、docs 与 media文档站点与媒体文件服务docs包含 Baserow 全部开发者文档的 Markdown 文件内容会被自动发布到 Baserow 的官方文档站点。你正在阅读目录结构说明的这份文件就位于 docs/development/directory-structure.mddocs/development 下还有本地/Docker 开发环境、测试运行、e2e 测试、插件开发等系列文档可与本文互为参照。media文档记载该目录包含一个基于 nginx 的 Docker 镜像用于在 Baserow 的 docker 部署中托管用户上传的文件。其存在的原因是一条 Django 的安全约定非 DEBUG 模式下 Django 不会代管媒体文件必须自行运行一个 web server 来提供这些静态资产。需要说明的是在当前仓库根目录结构中已没有独立的media/目录媒体服务职责已并入现有容器编排这一节更多是理解 Baserow 上传文件服务链路的历史背景。五、从目录结构出发的动手速查结合目录布局与 backend/justfile 的分组一个典型开发者的工作路径如下初始化环境在backend/下执行just inituv 建 venv、锁依赖、装依赖并准备本地 code runner 运行时跑测试just testjustfile 会以tests:../premium/backend/tests:../enterprise/backend/tests作为PYTHONPATH调用pytest -c pytest.ini见 backend/justfile#L312-L322起开发服务器just dev即run-dev-server执行baserow runserver默认绑定0.0.0.0:8000日志写入/tmp/baserow-backend.log执行管理命令just m cmd或直接baserow cmd如baserow migrate、baserow makemigrations --checkCI 中用check-migrations配方校验。最后用一张表收束全文目录/文件角色关键入口backend/src/baserow/apiREST API 的 Django 应用默认安装urls.py以api命名空间挂到根路由backend/src/baserow/config环境设置与根路由/WSGI/ASGIsettings/base.py、urls.py、wsgi.py、asgi.pybackend/src/baserow/core必需 appworkspace/application 核心概念—backend/src/baserow/contrib可选功能 appdatabase、automation、builder、dashboard、integrations—backend/tests/baserow与 src 同构的测试树 fixturesconftest.py、各目录fixtures/web-frontend/modulesNuxt 业务模块遵循 Nuxt 目录约定nuxt.config.tsdocs开发者文档Markdown自动发布到文档站点docs/index.mdbackend/justfile / web-frontend/justfile各自的依赖安装、lint、测试、服务命令just --list掌握以上结构后你在 Baserow 中定位任何功能都能按功能域 → 对应目录 → urls/serializers/测试同名文件这条固定路径快速下钻这正是这套目录结构设计的意图所在。【免费下载链接】baserowBuild databases, automations, apps agents with AI — no code. Open source platform available on cloud and self-hosted. GDPR, HIPAA, SOC 2 compliant. Best Airtable alternative.项目地址: https://gitcode.com/GitHub_Trending/ba/baserow创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考