Go Boilerplate

GitHub Repository

精简的 Go + Dodo Payments 样板

概述

Go boilerplate 是一个简洁的 Go 服务器，可从定价页面销售你的 Dodo Payments 产品。它会创建 checkout sessions、验证并处理 webhooks，以及打开 Customer Portal。将其克隆下来，作为你自己的 Go 后端的起点。

此 boilerplate 需要 Go 1.24.4 或更高版本，该版本已设置在其 go.mod 中。它采用 cmd、internal 和 templates 布局，使用 Go HTML templates 渲染定价页面，并通过 dodopayments-go SDK 调用 Dodo Payments API。

特性

快速设置：克隆仓库，将 API keys 添加到 .env，然后使用 make run 启动服务器。
支付集成：使用 dodopayments-go SDK 创建 checkout sessions 的 checkout 流程。
现代 UI：使用 Go HTML templates 和 Tailwind CSS 构建的深色主题定价页面。
Webhook 处理：在处理事件之前验证每个 webhook 的签名。
Customer Portal：通过 Customer Portal 自助管理订阅。
Go 最佳实践：采用 cmd、internal 和 templates 的简洁项目布局。
预填充 Checkout：将客户的姓名和电子邮件传递给 checkout，因此客户无需再次输入。

先决条件

开始之前，你需要准备：

Go 1.24.4 或更高版本。使用 go version 检查版本。
一个 Dodo Payments 账户，用于在 dashboard 中创建 API key 和 webhook signing key。
至少一个产品，在 dashboard 的 Products 下创建。

快速开始

Clone the Repository

git clone https://github.com/dodopayments/go-boilerplate.git
cd go-boilerplate

Install Dependencies

make install

make install 会运行 go mod download，然后运行 go mod tidy。若要在不使用 make 的情况下下载 modules，请运行：

go mod download

Get API Credentials

在 Dodo Payments 注册，然后从 dashboard 复制两个 key：

API Key： Developer → API Keys
Webhook Key： Developer → Webhooks。每个 webhook endpoint 都有自己的 signing key。若要创建可访问本地服务器的 endpoint，请参阅在本地测试 Webhooks。

开发期间，请在 test mode 中创建两个 key。若要切换到 test mode，请关闭 dashboard 侧边栏中的 Live Mode 开关。

Configure Environment Variables

根据模板，在项目根目录创建一个 .env 文件：

cp .env.example .env

在 .env 中设置以下值：

.env

DODO_PAYMENTS_API_KEY=your_api_key_here
DODO_PAYMENTS_WEBHOOK_KEY=your_webhook_signing_key_here
DODO_PAYMENTS_RETURN_URL=http://localhost:8000
DODO_PAYMENTS_ENVIRONMENT=test_mode
PORT=8000

服务器启动时会读取这些变量：

变量	必需	默认值	用途
`DODO_PAYMENTS_API_KEY`	是	None	对访问 Dodo Payments API 的请求进行身份验证。
`DODO_PAYMENTS_WEBHOOK_KEY`	是	None	验证传入 webhooks 的签名。
`DODO_PAYMENTS_RETURN_URL`	否	`http://localhost:8080`	checkout 在支付完成后将客户重定向到的 URL。
`DODO_PAYMENTS_ENVIRONMENT`	否	`test_mode`	`test_mode` 或 `live_mode`。
`PORT`	否	`8000`	服务器监听的端口。

如果缺少任一必需 key，服务器会在启动时退出。.env.example 会将 PORT 和 DODO_PAYMENTS_RETURN_URL 设置为端口 8080。本页面使用端口 8000，因此请按示例将两者都设置为 8000，或者在本页面的命令中将 8000 替换为 8080。

切勿将 .env 文件提交到版本控制系统。仓库中的 .gitignore 已将其排除。

Add Your Products

将 internal/lib/products.go 中的示例产品替换为你的产品。从 dashboard 的 Products 中复制每个产品 ID：

var Products = []Product{
    {
        ProductID:   "pdt_001", // Replace with your product ID
        Name:        "Basic Plan",
        Description: "Get access to basic features and support",
        Price:       9999, // in cents
        Features: []string{
            "Access to basic features",
            "Email support",
            "1 Team member",
            "Basic analytics",
        },
    },
    // ... add more products
}

Price 仅设置定价页面显示的价格，单位为最小货币单位：9999 显示为 $99.99。Checkout 会收取 Dodo Payments 中产品的价格。

Run the Development Server

make run

make run 会将服务器构建到 bin/server 中并启动服务器。若要在不先构建 binary 的情况下运行服务器，请运行：

go run cmd/server/main.go

打开 http://localhost:8000 查看定价页面。

你会看到一个深色主题的定价页面，其中列出了你的产品，可以直接购买。

项目结构

仓库采用以下布局：

go-boilerplate/
├── cmd/
│   └── server/             # Application entry point (main.go)
├── internal/
│   ├── api/                # API handlers: checkout.go, portal.go, webhook.go
│   ├── core/               # Configuration loading (config.go)
│   └── lib/                # Shared logic: products.go, customers.go
├── templates/              # HTML templates: base.html, index.html
├── Makefile                # Build and run commands
├── go.mod                  # Go module definition
├── go.sum                  # Dependency checksums
├── .env.example            # Environment template
└── README.md

API Endpoints

boilerplate 包含以下预配置的 endpoints：

Endpoint	Method	Description
`/`	GET	列出 `internal/lib/products.go` 中产品的定价页面。
`/api/checkout`	POST	创建 checkout session。发送 `product_id`，以及可选的 `quantity`（默认值为 `1`）和 `customer`（`email`、`name`、`phone`）。返回 `session_id` 和 `checkout_url`。
`/api/webhook`	POST	验证并处理 Dodo Payments webhooks。签名检查失败时返回 `401`。
`/api/customer-portal`	POST	在 `portal_url` 中返回 Customer Portal 链接。发送 `customer_id`，或发送带有可选 `name` 的 `email`。仅提供电子邮件时，handler 会查找客户；如果客户不存在，则创建客户。
`/health`	GET	Health check。返回 `OK`。

自定义

更新产品信息

编辑 internal/lib/products.go 以更改：

产品 ID（来自 Dodo Payments dashboard 中的 Products）
名称
定价页面上显示的价格
功能
描述

var Products = []Product{
    {
        ProductID:   "pdt_001", // Replace with your product ID
        Name:        "Basic Plan",
        Description: "Get access to basic features and support",
        Price:       9999,
        Features: []string{
            "Access to basic features",
            "Email support",
            "1 Team member",
            "Basic analytics",
        },
    },
}

定价页面模板会为每个价格添加 /mo 后缀；当 Price 大于或等于 100000 时，会显示 Custom 而不是价格。若要更改此行为，请编辑 templates/index.html。

预填充客户数据

在 .env 中，handleCheckout 函数会将硬编码的客户数据发送到 /api/checkout。将其替换为已登录用户的数据：

const customerData = {
    name: "John Doe",       // Replace with actual logged-in user's name
    email: "john@example.com"  // Replace with actual logged-in user's email
};

handlePortal 函数会复用这些客户数据，并回退到相同的示例姓名和电子邮件。在生产应用中，请在两个函数中都从身份验证系统注入这些值。

Webhook Events

internal/api/webhook.go 使用 client.Webhooks.Unwrap 和 DODO_PAYMENTS_WEBHOOK_KEY 中的 key 验证每个请求，然后根据其 type 路由事件。以下事件都有对应的 handler，并且每个 handler 都会记录事件数据：

Event	Description
`payment.succeeded`	支付成功时触发
`payment.failed`	支付尝试失败时触发
`subscription.active`	订阅变为 active 时触发
`subscription.renewed`	订阅续订至下一个计费周期时触发
`subscription.updated`	任意订阅字段发生变化时触发
`subscription.cancelled`	订阅取消时触发

handler 还会接受 subscription.on_hold、subscription.failed、subscription.expired 和 subscription.plan_changed，但不执行任何操作；对于其他所有事件类型，则记录为未处理。每个经过验证的事件都会返回 200。有关所有事件类型，请参阅 Webhook Event Guide。将你的业务逻辑添加到 handler 函数中，以便：

更新数据库中的用户权限
发送确认电子邮件
为数字产品配置访问权限
跟踪分析数据和指标

在本地测试 Webhooks

Dodo Payments 无法访问 localhost。若要在开发期间接收 webhooks，请使用 ngrok 等 tunnel 暴露本地服务器：

ngrok http 8000

在 Dodo Payments Dashboard 中，添加一个 endpoint，将 ngrok 输出的 forwarding URL 后追加 /api/webhook：

https://your-ngrok-url.ngrok.io/api/webhook

将 endpoint 的 signing key 复制到 DODO_PAYMENTS_WEBHOOK_KEY，然后重启服务器。

部署

构建生产版本

make build 会将服务器编译到 bin/server：

make build

若要在不使用 make 的情况下构建并启动 binary，请运行：

go build -o bin/server cmd/server/main.go
./bin/server

部署到 Vercel

[

](https://vercel.com/new/clone?repository-url=https://github.com/dodopayments/go-boilerplate) 部署完成后，将 .env 文件中的变量添加到 Vercel 项目设置中，因为 .env 不在仓库中。然后在 dashboard 中将 webhook endpoint 设置为 https://yourdomain.com/api/webhook。

Docker

在项目根目录创建一个 Dockerfile。构建阶段必须使用 Go 1.24.4 或更高版本，以匹配 go.mod：

FROM golang:1.24-alpine AS builder

WORKDIR /app
COPY go.mod go.sum ./
RUN go mod download

COPY . .
RUN go build -o bin/server cmd/server/main.go

FROM alpine:latest
WORKDIR /app
COPY --from=builder /app/bin/server .
COPY --from=builder /app/templates ./templates

EXPOSE 8000
CMD ["./server"]

最终 image 会将 templates/ 复制到 binary 旁边，因为服务器会从工作目录加载 templates。构建并运行 image：

docker build -t go-dodo .
docker run -p 8000:8000 --env-file .env go-dodo

容器会监听 .env 中 PORT 的值，因此请保持 PORT=8000 与端口映射一致。

生产环境注意事项

部署到生产环境之前：

将 DODO_PAYMENTS_ENVIRONMENT 设置为 live_mode。
使用 dashboard 中的 live mode API key。
将 webhook endpoint 指向生产域名，并使用该 endpoint 的 signing key。
将 DODO_PAYMENTS_RETURN_URL 设置为生产域名上的页面。
通过 HTTPS 提供所有 endpoint。

故障排除

Build errors or missing dependencies

确认 go version 报告的 Go 版本为 1.24.4 或更高版本，然后再次下载 modules：

go mod tidy
go mod download

Checkout session creation fails

常见原因：

产品 ID 无效。确认它在与你的 API key 相同的 mode 下存在于 Products 中。
.env 中的 API key 或 DODO_PAYMENTS_ENVIRONMENT 错误。test mode key 需要使用 test_mode。
如需查看确切错误，请检查服务器日志。handler 会在返回 500 之前记录每个失败的请求。

Webhooks not receiving events

如需进行本地测试，请使用 ngrok 暴露服务器：

ngrok http 8000

将 Dodo Payments dashboard 中的 webhook URL 设置为 ngrok URL。然后将 .env 中的 DODO_PAYMENTS_WEBHOOK_KEY 设置为该 endpoint 的 signing key。如果服务器记录 webhook verification failed，则表示 key 与 endpoint 不匹配。

Templates not loading

服务器会从工作目录加载 templates/base.html 和 templates/index.html。从项目根目录启动服务器，或更改 cmd/server/main.go 中的 template paths。

了解更多

Go SDK

完整的 Go SDK 文档

Webhooks Documentation

了解所有 webhook 事件和最佳实践

Checkout Sessions

深入了解 checkout session 配置

API Reference

完整的 Dodo Payments API 文档

支持

如需 boilerplate 方面的帮助：

在 Discord 社区中提问。
查看 GitHub 仓库中的问题和更新。
联系支持团队。

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

GitHub Repository

概述

特性

先决条件

快速开始

项目结构

API Endpoints

自定义

更新产品信息

预填充客户数据

Webhook Events

在本地测试 Webhooks

部署

构建生产版本

部署到 Vercel

Docker

生产环境注意事项

故障排除

了解更多

Go SDK

Webhooks Documentation

Checkout Sessions

API Reference

支持

GitHub Repository

​概述

​特性

​先决条件

​快速开始

​项目结构

​API Endpoints

​自定义

​更新产品信息

​预填充客户数据

​Webhook Events

​在本地测试 Webhooks

​部署

​构建生产版本

​部署到 Vercel

​Docker

​生产环境注意事项

​故障排除

​了解更多

Go SDK

Webhooks Documentation

Checkout Sessions

API Reference

​支持

概述

特性

先决条件

快速开始

项目结构

API Endpoints

自定义

更新产品信息

预填充客户数据

Webhook Events

在本地测试 Webhooks

部署

构建生产版本

部署到 Vercel

Docker

生产环境注意事项

故障排除

了解更多

支持