> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Go Boilerplate

> 克隆一个简洁的 Go 服务器，该服务器使用 dodopayments-go SDK 创建 Dodo Payments checkout sessions、验证 webhooks，并打开 Customer Portal。

> **[GitHub Repository](https://github.com/dodopayments/go-boilerplate)**
>
> 精简的 Go + Dodo Payments 样板

## 概述

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

> [!NOTE]
>
> 此 boilerplate 需要 Go 1.24.4 或更高版本，该版本已设置在其 `go.mod` 中。它采用 `cmd`、`internal` 和 `templates` 布局，使用 Go HTML templates 渲染定价页面，并通过 [`dodopayments-go`](/developer-resources/sdks/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** 下创建。

## 快速开始

**1. Clone the Repository**

```bash theme={null}
git clone https://github.com/dodopayments/go-boilerplate.git
cd go-boilerplate
```

**2. Install Dependencies**

```bash theme={null}
make install
```

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

```bash theme={null}
go mod download
```

**3. Get API Credentials**

在 [Dodo Payments](https://dodopayments.com/) 注册，然后从 dashboard 复制两个 key：

* **API Key：** [Developer → API Keys](https://app.dodopayments.com/developer/api-keys)
* **Webhook Key：** [Developer → Webhooks](https://app.dodopayments.com/developer/webhooks)。每个 webhook endpoint 都有自己的 signing key。若要创建可访问本地服务器的 endpoint，请参阅[在本地测试 Webhooks](#testing-webhooks-locally)。

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

**4. Configure Environment Variables**

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

```bash theme={null}
cp .env.example .env
```

在 `.env` 中设置以下值：

```bash .env theme={null}
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`。

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

**5. Add Your Products**

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

```go theme={null}
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 中产品的价格。

**6. Run the Development Server**

```bash theme={null}
make run
```

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

```bash theme={null}
go run cmd/server/main.go
```

打开 [http://localhost:8000](http://localhost:8000) 查看定价页面。

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

## 项目结构

仓库采用以下布局：

```text theme={null}
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**）
* 名称
* 定价页面上显示的价格
* 功能
* 描述

```go theme={null}
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`。将其替换为已登录用户的数据：

```javascript theme={null}
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](/developer-resources/webhooks/intents/webhook-events-guide)。

将你的业务逻辑添加到 handler 函数中，以便：

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

## 在本地测试 Webhooks

Dodo Payments 无法访问 `localhost`。若要在开发期间接收 webhooks，请使用 [ngrok](https://ngrok.com/) 等 tunnel 暴露本地服务器：

```bash theme={null}
ngrok http 8000
```

在 [Dodo Payments Dashboard](https://app.dodopayments.com/developer/webhooks) 中，添加一个 endpoint，将 ngrok 输出的 forwarding URL 后追加 `/api/webhook`：

```text theme={null}
https://your-ngrok-url.ngrok.io/api/webhook
```

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

## 部署

### 构建生产版本

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

```bash theme={null}
make build
```

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

```bash theme={null}
go build -o bin/server cmd/server/main.go
./bin/server
```

### 部署到 Vercel

\[

![使用 Vercel 部署](https://vercel.com/button)

]\([https://vercel.com/new/clone?repository-url=https://github.com/dodopayments/go-boilerplate](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`：

```dockerfile theme={null}
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：

```bash theme={null}
docker build -t go-dodo .
docker run -p 8000:8000 --env-file .env go-dodo
```

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

### 生产环境注意事项

> [!WARNING]
>
> 部署到生产环境之前：
>
> * 将 `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：
>
> ```bash theme={null}
> 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](https://ngrok.com) 暴露服务器：
>
> ```bash theme={null}
> ngrok http 8000
> ```
>
> 将 [Dodo Payments dashboard](https://app.dodopayments.com/developer/webhooks) 中的 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](/developer-resources/sdks/go)**
>
> 完整的 Go SDK 文档

> **[Webhooks Documentation](/developer-resources/webhooks)**
>
> 了解所有 webhook 事件和最佳实践

> **[Checkout Sessions](/developer-resources/checkout-session)**
>
> 深入了解 checkout session 配置

> **[API Reference](/api-reference/introduction)**
>
> 完整的 Dodo Payments API 文档

## 支持

如需 boilerplate 方面的帮助：

* 在 [Discord 社区](https://discord.gg/bYqAp4ayYh)中提问。
* 查看 [GitHub 仓库](https://github.com/dodopayments/go-boilerplate)中的问题和更新。
* 联系 [支持团队](mailto:support@dodopayments.com)。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.