深度拆解 open-saas从分层架构到支付全链路的 SaaS 全栈模板实战指南【免费下载链接】open-saasA 100% free modern JS SaaS boilerplate (React, NodeJS, Prisma). Full-featured: Auth (email, google, github, slack, MS), Email sending, Background jobs, Landing page, Payments (Stripe, Polar.sh), Shadcn UI, S3 file upload. AI-ready with tailored AGENTS.md, skills, and Claude Code plugin. One cmd deploy. Powered by Wasp full-stack framework.项目地址: https://gitcode.com/GitHub_Trending/op/open-saasopen-saas 是一个 100% 免费、基于 Wasp 框架的 SaaS 启动模板内置认证、邮件、Stripe 支付、S3 文件上传和管理后台等生产级模块。这篇文章拆解它的分层架构与核心 API 设计并沿一次 Stripe 订阅付费走完全链路最后给出三步跑通的命令。️ 架构全景一次请求从哪来、到哪去先看骨架open-saas 的 API 设计有四个特征模块化声明入口 main.wasp.ts 不写任何业务逻辑只把 auth、user、payment、fileUpload、analytics、admin 六个 spec 模块组装起来每个模块自带路由、操作和权限声明。分层清晰前端React shadcn/ui→ Wasp operations业务逻辑 权限守卫→ Prisma数据访问三层operations 是唯一业务入口客户端拿不到数据库。类型安全贯穿所有操作入参用 Zod schema 定义返回类型由 Wasp 推导前后端共享 shared 里的公共类型改名即报错。可插拔支付paymentProcessor.ts 定义统一接口Stripe / Lemon Squeezy / Polar 三家实现任选其一切换只改一行导出。一次典型请求的流转浏览器调用 Wasp operation → 服务端执行 401/403 权限守卫 → Zod 校验入参 → Prisma 读写数据库 → 结果或标准 HttpError 返回前端。open-saas 管理后台用户列表、订阅状态与营收数据都来自同一套 operations⚙️ 核心能力深拆权限、校验、支付计划三个最有代表性的能力直接看源码怎么写的。用户权限判定两层守卫怎么写管理端操作统一走「未登录 401 → 非管理员 403」两道守卫见 user/operations.ts// 每道守卫失败都抛出带状态码的 HttpError前端可统一处理 if (!context.user) { throw new HttpError(401, Only authenticated users are allowed...); } if (!context.user.isAdmin) { throw new HttpError(403, Only admins are allowed to perform this operation); }设计要点权限判断放在服务端 context 上而不是信任前端传来的任何标志位分页查询getPaginatedUsers也在同一文件里用$transaction一次取回分页数据与总数避免两次往返。输入校验Zod schema 统一拦截所有操作入参不直接消费而是过一遍 server/validation.ts 的公共函数const parseResult schema.safeParse(rawArgs); if (!parseResult.success) { console.error(new Error(Operation arguments validation failed:\n z.prettifyError(parseResult.error), { cause: parseResult.error })); throw new HttpError(400, Operation arguments validation failed, { cause: parseResult.error }); }好处是错误日志带完整 schema 路径生产环境排查参数问题不用猜同时 400 响应体不泄露内部结构。支付计划一份类型定义前后端共用定价页展示什么、后端接受什么由 payment/plans.ts 单一事实来源决定export enum PaymentPlanId { Hobby hobby, Pro pro, Credits10 credits10, }paymentPlans用satisfies约束确保每个计划都有对应 effect订阅或点数新增计划时编译器会逼你补齐所有引用点。 端到端走查一次 Stripe 订阅付费的完整链路以用户点击「订阅 Pro」为例按时间顺序走一遍。1. 创建结账会话。前端调用generateCheckoutSession操作先查context.user未登录直接 401Zod 校验计划 ID再要求用户必须绑定邮箱无邮箱抛 403最后委托给paymentProcessor.createCheckoutSession拿到 Stripe 会话 URL 返回前端前端跳转过去完成付款。2. Stripe 回传 webhook。付款完成后 Stripe 推送invoice.paid等事件到 stripe/webhook.ts。注意一个细节Stripe 验签需要原始请求体所以中间件用express.raw替换了默认的express.json。3. 事件分发与状态落库。webhook 用 switch 分发三类事件invoice.paid更新订阅状态并发邮件、customer.subscription.updated同步状态变更、customer.subscription.deleted标记取消未处理的事件在开发环境仅记录日志生产环境打印错误后返回 204避免 Stripe 无限重试。Stripe 后台配置测试产品价格 ID 与模板内的 PaymentPlanId 对应出错分支怎么看webhook 处理异常时返回 400/500 并打印堆栈事件会由 Stripe 重试用户侧的 401/403/400 则被前端捕获统一 toast 提示错误语义由 HttpError 状态码承载前端不需要解析错误文案。️ 上生产前这几个点不能省认证别只留邮箱登录auth.wasp.ts 里 Google、GitHub、Discord 均已预置取消注释 配好 OAuth 环境变量即可启用。webhook 必须配置验签密钥在 Stripe 后台注册 endpoint 时填STRIPE_WEBHOOK_SIGNING_SECRET只订阅你真正处理的事件。环境变量走 schema 校验serverEnvValidationSchema在服务启动时校验缺配置直接拒绝启动比运行时报错好排查。水平扩展友好服务端无状态session 由 Wasp 管理文件走 S3 预签名 URL 直传扩容只需加副本 托管 Postgres。保留 e2e 测试e2e-tests 目录用 Playwright 覆盖登录跳转、定价页等关键路径改完核心流程跑一遍再上线。 三步跑通从 clone 到看到落地页git clone https://gitcode.com/GitHub_Trending/op/open-saas cd open-saas/template/app npm installwasp start db wasp db migrate-dev wasp start打开 http://localhost:3000看到带 Hero、示例轮播和定价区的落地页即成功访问 /signup 注册后用wasp db seed可生成一批模拟用户来体验管理后台。 想继续深入看这里stripe/webhook.ts事件分发与重试语义的完整写法换支付商时最值得对照。auth.wasp.ts所有登录方式的装配点新增 OAuth 只改这一个文件。deploying.mdx部署流程与 Stripe webhook 注册的官方指南。paymentProcessor.ts三家支付处理器的统一接口定义理解「可插拔」的关键。把认证、支付、文件上传这些每个 SaaS 都要重写的轮子收敛成可插拔模块再配上 AI 协作用的 AGENTS.md 与 e2e 测试open-saas 的价值不在某个单点功能而在于把「从 demo 到生产」的路径压到了最短。【免费下载链接】open-saasA 100% free modern JS SaaS boilerplate (React, NodeJS, Prisma). Full-featured: Auth (email, google, github, slack, MS), Email sending, Background jobs, Landing page, Payments (Stripe, Polar.sh), Shadcn UI, S3 file upload. AI-ready with tailored AGENTS.md, skills, and Claude Code plugin. One cmd deploy. Powered by Wasp full-stack framework.项目地址: https://gitcode.com/GitHub_Trending/op/open-saas创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
深度拆解 open-saas从分层架构到支付全链路的 SaaS 全栈模板实战指南【免费下载链接】open-saasA 100% free modern JS SaaS boilerplate (React, NodeJS, Prisma). Full-featured: Auth (email, google, github, slack, MS), Email sending, Background jobs, Landing page, Payments (Stripe, Polar.sh), Shadcn UI, S3 file upload. AI-ready with tailored AGENTS.md, skills, and Claude Code plugin. One cmd deploy. Powered by Wasp full-stack framework.项目地址: https://gitcode.com/GitHub_Trending/op/open-saasopen-saas 是一个 100% 免费、基于 Wasp 框架的 SaaS 启动模板内置认证、邮件、Stripe 支付、S3 文件上传和管理后台等生产级模块。这篇文章拆解它的分层架构与核心 API 设计并沿一次 Stripe 订阅付费走完全链路最后给出三步跑通的命令。️ 架构全景一次请求从哪来、到哪去先看骨架open-saas 的 API 设计有四个特征模块化声明入口 main.wasp.ts 不写任何业务逻辑只把 auth、user、payment、fileUpload、analytics、admin 六个 spec 模块组装起来每个模块自带路由、操作和权限声明。分层清晰前端React shadcn/ui→ Wasp operations业务逻辑 权限守卫→ Prisma数据访问三层operations 是唯一业务入口客户端拿不到数据库。类型安全贯穿所有操作入参用 Zod schema 定义返回类型由 Wasp 推导前后端共享 shared 里的公共类型改名即报错。可插拔支付paymentProcessor.ts 定义统一接口Stripe / Lemon Squeezy / Polar 三家实现任选其一切换只改一行导出。一次典型请求的流转浏览器调用 Wasp operation → 服务端执行 401/403 权限守卫 → Zod 校验入参 → Prisma 读写数据库 → 结果或标准 HttpError 返回前端。open-saas 管理后台用户列表、订阅状态与营收数据都来自同一套 operations⚙️ 核心能力深拆权限、校验、支付计划三个最有代表性的能力直接看源码怎么写的。用户权限判定两层守卫怎么写管理端操作统一走「未登录 401 → 非管理员 403」两道守卫见 user/operations.ts// 每道守卫失败都抛出带状态码的 HttpError前端可统一处理 if (!context.user) { throw new HttpError(401, Only authenticated users are allowed...); } if (!context.user.isAdmin) { throw new HttpError(403, Only admins are allowed to perform this operation); }设计要点权限判断放在服务端 context 上而不是信任前端传来的任何标志位分页查询getPaginatedUsers也在同一文件里用$transaction一次取回分页数据与总数避免两次往返。输入校验Zod schema 统一拦截所有操作入参不直接消费而是过一遍 server/validation.ts 的公共函数const parseResult schema.safeParse(rawArgs); if (!parseResult.success) { console.error(new Error(Operation arguments validation failed:\n z.prettifyError(parseResult.error), { cause: parseResult.error })); throw new HttpError(400, Operation arguments validation failed, { cause: parseResult.error }); }好处是错误日志带完整 schema 路径生产环境排查参数问题不用猜同时 400 响应体不泄露内部结构。支付计划一份类型定义前后端共用定价页展示什么、后端接受什么由 payment/plans.ts 单一事实来源决定export enum PaymentPlanId { Hobby hobby, Pro pro, Credits10 credits10, }paymentPlans用satisfies约束确保每个计划都有对应 effect订阅或点数新增计划时编译器会逼你补齐所有引用点。 端到端走查一次 Stripe 订阅付费的完整链路以用户点击「订阅 Pro」为例按时间顺序走一遍。1. 创建结账会话。前端调用generateCheckoutSession操作先查context.user未登录直接 401Zod 校验计划 ID再要求用户必须绑定邮箱无邮箱抛 403最后委托给paymentProcessor.createCheckoutSession拿到 Stripe 会话 URL 返回前端前端跳转过去完成付款。2. Stripe 回传 webhook。付款完成后 Stripe 推送invoice.paid等事件到 stripe/webhook.ts。注意一个细节Stripe 验签需要原始请求体所以中间件用express.raw替换了默认的express.json。3. 事件分发与状态落库。webhook 用 switch 分发三类事件invoice.paid更新订阅状态并发邮件、customer.subscription.updated同步状态变更、customer.subscription.deleted标记取消未处理的事件在开发环境仅记录日志生产环境打印错误后返回 204避免 Stripe 无限重试。Stripe 后台配置测试产品价格 ID 与模板内的 PaymentPlanId 对应出错分支怎么看webhook 处理异常时返回 400/500 并打印堆栈事件会由 Stripe 重试用户侧的 401/403/400 则被前端捕获统一 toast 提示错误语义由 HttpError 状态码承载前端不需要解析错误文案。️ 上生产前这几个点不能省认证别只留邮箱登录auth.wasp.ts 里 Google、GitHub、Discord 均已预置取消注释 配好 OAuth 环境变量即可启用。webhook 必须配置验签密钥在 Stripe 后台注册 endpoint 时填STRIPE_WEBHOOK_SIGNING_SECRET只订阅你真正处理的事件。环境变量走 schema 校验serverEnvValidationSchema在服务启动时校验缺配置直接拒绝启动比运行时报错好排查。水平扩展友好服务端无状态session 由 Wasp 管理文件走 S3 预签名 URL 直传扩容只需加副本 托管 Postgres。保留 e2e 测试e2e-tests 目录用 Playwright 覆盖登录跳转、定价页等关键路径改完核心流程跑一遍再上线。 三步跑通从 clone 到看到落地页git clone https://gitcode.com/GitHub_Trending/op/open-saas cd open-saas/template/app npm installwasp start db wasp db migrate-dev wasp start打开 http://localhost:3000看到带 Hero、示例轮播和定价区的落地页即成功访问 /signup 注册后用wasp db seed可生成一批模拟用户来体验管理后台。 想继续深入看这里stripe/webhook.ts事件分发与重试语义的完整写法换支付商时最值得对照。auth.wasp.ts所有登录方式的装配点新增 OAuth 只改这一个文件。deploying.mdx部署流程与 Stripe webhook 注册的官方指南。paymentProcessor.ts三家支付处理器的统一接口定义理解「可插拔」的关键。把认证、支付、文件上传这些每个 SaaS 都要重写的轮子收敛成可插拔模块再配上 AI 协作用的 AGENTS.md 与 e2e 测试open-saas 的价值不在某个单点功能而在于把「从 demo 到生产」的路径压到了最短。【免费下载链接】open-saasA 100% free modern JS SaaS boilerplate (React, NodeJS, Prisma). Full-featured: Auth (email, google, github, slack, MS), Email sending, Background jobs, Landing page, Payments (Stripe, Polar.sh), Shadcn UI, S3 file upload. AI-ready with tailored AGENTS.md, skills, and Claude Code plugin. One cmd deploy. Powered by Wasp full-stack framework.项目地址: https://gitcode.com/GitHub_Trending/op/open-saas创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
