深入理解 RedwoodJS 项目文件结构：api / web / scripts 三端（Side）架构全解析

深入理解 RedwoodJS 项目文件结构api / web / scripts 三端Side架构全解析【免费下载链接】redwoodRedwoodGraphQL项目地址: https://gitcode.com/gh_mirrors/re/redwood本篇技术指南以 RedwoodJS 官方教程第一章《Redwood File Structure》为骨架系统拆解一个全新 Redwood 应用生成出的目录结构后端api、前端web与独立脚本scripts三端如何分工、每个目录与文件承担什么职责以及它们如何通过 Yarn Workspaces 协作。读完本文你将掌握 RedwoodJS 应用的目录组织范式能够快速定位数据库 Schema、GraphQL 定义、Service 业务逻辑、路由与页面等关键代码并理解约定优于配置在 Redwood 中是如何落地的。顶层结构api / scripts / web 三端布局一个新创建的 RedwoodJS 应用在顶层会有三个目录api、scripts和web配置文件暂不展开。RedwoodJS 刻意将后端api与前端web的关注点分离到代码库中各自独立的路径下——这正是 Yarn 所称的workspaces工作区而在 Redwood 的语境里它们被称作sides端。这种一应用双端的布局是理解整个框架的前提前端只管 React 界面后端只管 GraphQL API 与数据访问二者通过约定好的目录与命名自动建立关联。├── api │ ├── db │ │ ├── schema.prisma │ ├── dist │ ├── src │ │ ├── directives │ │ │ ├── requireAuth │ │ │ └── skipAuth │ │ ├── functions │ │ │ └── graphql.js │ │ ├── graphql │ │ ├── lib │ │ │ ├── auth.js │ │ │ ├── db.js │ │ │ └── logger.js │ │ └── services │ └── types │ ├── scripts │ └── seed.js │ └── web ├── public │ ├── favicon.png │ ├── README.md │ └── robots.txt └── src ├── components ├── layouts ├── pages │ ├── FatalErrorPage │ │ └── FatalErrorPage.js │ └── NotFoundPage │ └── NotFoundPage.js ├── App.js ├── index.css ├── index.html └── Routes.jsTypeScript 项目中仅扩展名不同graphql.ts、auth.ts、FatalErrorPage.tsx、Routes.tsx等目录骨架完全一致。当前仓库的__fixtures__/empty-project就是一个完整的 TS 版空项目样例其实际目录树与本结构一一对应。由于前后端分属两个 Yarn workspace后续安装依赖时必须显式指明包要装进哪一端例如仅示意语法勿直接执行yarn workspace web add marked yarn workspace api add better-fsscripts目录则用于存放与api、web两端无直接关联、需要从命令行运行的 Node 脚本。其中的seed.{js,ts}用于向数据库填充应用运行所必需的基础数据比如管理员账号或站点配置。在空项目中该文件默认只是一段占位逻辑——见 seed.ts它导出一个async函数注释中演示了如何用db.user.createMany()批量写入种子用户并在末尾打印提示信息。api 目录后端全解析api目录下共有四个子目录db、dist、src与types。db数据库的管道schema.prisma存放数据库 schema表与列的完整定义。以空项目模板为例其内容如下见 schema.prismadatasource db { provider sqlite url env(DATABASE_URL) directUrl env(DIRECT_URL) } generator client { provider prisma-client-js binaryTargets native } model UserExample { id Int id default(autoincrement()) email String unique name String? }默认数据源是 SQLite通过DATABASE_URL环境变量读取连接串generator client声明使用 Prisma Client 生成器。第一次添加数据表并执行迁移后这里还会自动出现 SQLite 数据库文件dev.db以及一个migrations目录——migrations中的迁移文件记录了数据库 schema 随时间变化的每一次快照是团队协作与版本回滚的基础。dist编译产物dist存放 api 端的编译输出开发阶段无需关心构建时由 Redwood 自动生成。src全部后端源码api/src下包含五个目录directives存放 GraphQL schema directivesschema 指令用于控制查询访问权限或转换字段值。新项目预置两个指令requireAuth校验用户是否已认证并匹配可选的角色列表。空项目中的实现见 requireAuth.ts它通过createValidatorDirective定义requireAuth(roles: [String])在validate中调用src/lib/auth导出的requireAuth。skipAuth跳过鉴权、允许公开访问。实现见 skipAuth.tsvalidate为空函数即放行。functions除 Redwood 自动生成的graphql.{js,ts}外存放应用所需的任何 lambda functionsimport { createGraphQLHandler } from redwoodjs/graphql-server import directives from src/directives/**/*.{js,ts} import sdls from src/graphql/**/*.sdl.{js,ts} import services from src/services/**/*.{js,ts} import { db } from src/lib/db import { logger } from src/lib/logger export const handler createGraphQLHandler({ loggerConfig: { logger, options: {} }, directives, sdls, services, onException: () { // Disconnect from your database with an unhandled exception. db.$disconnect() }, })注意其中的 glob 通配符src/directives/**/*、src/graphql/**/*.sdl、src/services/**/*——这揭示了 Redwood 的核心约定directives、SDL 与 services 会自动按目录扫描并注册进 GraphQL Handler这正是约定优于配置的底层实现。graphql存放用 Schema Definition LanguageSDL书写的 GraphQL schema 文件文件名以.sdl.{js,ts}结尾。SDL 声明了查询、变更与对应的 GraphQL 类型是前后端契约的载体。lib预置三个文件同时可存放其他放哪都不太合适的 api 侧代码auth.{js,ts}初始是添加鉴权功能的占位文件。空项目版本见 auth.ts内置三个基础函数isAuthenticated()目前恒返回true模拟已登录用户hasRole({ roles })判断角色参数是否传入requireAuth({ roles })委托给isAuthenticated()。注释明确说明真正接入认证后这里会被实现为真实逻辑。db.{js,ts}实例化 Prisma 数据库客户端用于与数据库通信。实现见 db.tsnew PrismaClient({ log: emitLogLevels([info, warn, error]) })并通过handlePrismaLogging将 Prisma 日志接入 Redwood logger。logger.{js,ts}配置日志。实现见 logger.ts调用createLogger({})创建基于 pino 的 logger可通过RedwoodLoggerOptions自定义options日志格式、脱敏、destination输出到文件或传输流与showConfig等。services存放与数据相关的业务逻辑。GraphQL 的查询/变更最终落在这里——也就是通常所说的resolvers解析器但其组织形式更强调可复用性同一份业务代码可以在应用的其他位置如后台任务、脚本直接调用而非仅仅服务于 GraphQL 层。types自动生成的类型types存放自动编译生成的 GraphQL 类型TypeScript 类型定义开发阶段可以忽略由 Redwood 在开发/构建流程中自动维护。web 目录前端全解析web目录对应前端 React 应用同样分为静态资源区与源码区。public静态资源区public存放不经过 React 组件处理的资源——它们会被原样复制到最终应用的根目录favicon.png浏览器标签页图标新应用默认使用 RedwoodJS logo。README.md说明何时、如何使用public文件夹存放静态资源并给出在组件内通过打包器导入资源的最佳实践。仓库中的 README.md 强调public中的文件会绕过 JS 模块系统直接复制进构建产物因此应克制使用仅放置 favicon、robots.txt、manifest、与打包器不兼容的库等一般场景优先在组件内import资源让打包器完成校验、路径处理与打包例如import logo from ./my-logo.jpg。robots.txt控制搜索引擎爬虫等 Web 索引器的抓取行为。src前端源码区components存放传统 React 组件以及 Redwood 特有的Cells一种数据驱动的声明式组件范式负责加载/空态/失败态/成功态的自动管理教程后续章节会专门讲解。layouts存放包裹内容、跨多个页面共享的 HTML/组件结构布局。pages存放页面组件可选地被包裹在 Layout 中是某个 URL 对应的落地页例如/articles/hello-world映射到一页/contact-us映射到另一页。新应用内置两个页面NotFoundPage.{js,tsx}当没有其他路由匹配时渲染。空项目版本见 NotFoundPage.tsx渲染居中显示的 404 Page Not Found。FatalErrorPage.{js,tsx}当出现无法恢复的未捕获错误否则应用会崩溃渲染为白屏时渲染。空项目版本见 FatalErrorPage.tsx注意其实现细节仅在NODE_ENV development时加载redwoodjs/web的开发版错误页生产构建中不包含该错误页同时注释提醒应尽量保持该页面简单避免它自身再抛错。App.{js,tsx}引导代码负责把整个 Redwood 应用拉起来。空项目版本见 App.tsx外层是FatalErrorBoundary内部依次包裹RedwoodProvider支持titleTemplate标题模板与RedwoodApolloProviderGraphQL 客户端最后挂载Routes /。index.css自定义 CSS 的起点。文档提到还有很多方案可选例如 TailwindCSS——用好之后可能整个应用生命周期都无需手写自定义 CSS。index.html标准的 React 应用起始 HTML 文件是浏览器首先收到的页面骨架。Routes.{js,tsx}路由定义负责把 URL 映射到某个 Page。空项目版本见 Routes.tsx其文件头注释揭示了页面自动导入约定src/pages下所有 Page 组件自动导入子目录需大写并作为组件名前缀例如src/pages/HomePage/HomePage.js对应HomePagesrc/pages/Admin/BooksPage/BooksPage.js对应AdminBooksPage。默认内容即一个Router加一条notfound兜底路由const Routes () { return ( Router Route notfound page{NotFoundPage} / /Router ) }配套配置文件redwood.toml虽然目录结构讲解暂时排除了配置文件但redwood.toml是让一个 Redwood 应用成为 Redwood 应用的关键见 redwood.toml。它按端声明配置[web]下的title、端口8910、apiUrl默认/.redwood/functions与需要暴露给前端的includeEnvironmentVariables[api]下的端口8911[browser]下的open true表示启动时自动打开浏览器。删除该文件后运行yarn rw dev会直接报错。小结与后续学习路线至此RedwoodJS 应用的骨架已经清晰api端承载数据库db、GraphQL 层directives/graphql/functions、基础能力lib与业务逻辑servicesweb端承载静态资源public与 React 应用components/layouts/pages/Routesscripts端承载独立的 Node 脚本。后续教程将在这份骨架之上逐目录深入创建数据表db/schema.prisma、编写 SDL 与 Service、通过rw g命令生成页面与布局、接入 Cells 与认证逐步把这些空目录填满成完整的应用。【免费下载链接】redwoodRedwoodGraphQL项目地址: https://gitcode.com/gh_mirrors/re/redwood创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考