Chuyển đến nội dung chính

Kho lưu trữ GitHub

Boilerplate Go + Dodo Payments tối thiểu

Tổng quan

Boilerplate Go cung cấp một điểm khởi đầu sẵn sàng cho sản xuất để tích hợp Dodo Payments với backend Go của bạn. Mẫu này bao gồm xử lý phiên thanh toán, xác minh webhook, tích hợp cổng khách hàng và tuân theo các thực tiễn tốt nhất của Go để giúp bạn bắt đầu chấp nhận thanh toán nhanh chóng.
Boilerplate này sử dụng Go 1.21+ với các mẫu kiến trúc sạch (cmd, internal, templates), các mẫu HTML, và SDK dodopayments-go để tích hợp API liền mạch.

Tính năng

  • Cài đặt nhanh - Bắt đầu trong chưa đầy 5 phút
  • Tích hợp thanh toán - Quy trình thanh toán được cấu hình sẵn sử dụng SDK dodopayments-go
  • Giao diện hiện đại - Trang giá sạch sẽ, chủ đề tối với các mẫu HTML
  • Xử lý Webhook - Xác minh và xử lý sự kiện thanh toán một cách an toàn
  • Cổng khách hàng - Quản lý đăng ký tự phục vụ
  • Thực tiễn tốt nhất của Go - Kiến trúc sạch với cmd, internal, và templates
  • Thanh toán tự động điền - Chứng minh việc truyền dữ liệu khách hàng để cải thiện UX

Điều kiện tiên quyết

Trước khi bạn bắt đầu, hãy đảm bảo bạn đã có:
  • Go 1.21+
  • Tài khoản Dodo Payments (để truy cập API và Webhook Keys từ bảng điều khiển)

Bắt đầu nhanh

1

Nhân bản kho lưu trữ

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

Cài đặt phụ thuộc

make install
Hoặc thủ công:
go mod download
3

Lấy thông tin xác thực API

Đăng ký tại Dodo Payments và lấy thông tin xác thực của bạn từ bảng điều khiển:
Hãy chắc chắn rằng bạn đang ở chế độ Kiểm tra trong khi phát triển!
4

Cấu hình biến môi trường

Tạo một tệp .env trong thư mục gốc:
cp .env.example .env
Cập nhật các giá trị với thông tin xác thực Dodo Payments của bạn:
.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
Không bao giờ cam kết tệp .env của bạn vào kiểm soát phiên bản. Nó đã được bao gồm trong .gitignore.
5

Thêm sản phẩm của bạn

Cập nhật internal/lib/products.go với các ID sản phẩm thực tế của bạn từ Dodo Payments:
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
}
6

Chạy máy chủ phát triển

make run
Hoặc thủ công:
go run cmd/server/main.go
Mở http://localhost:8000 để xem trang giá của bạn!
Bạn sẽ thấy một trang giá với chủ đề tối với các sản phẩm của bạn sẵn sàng để mua.

Cấu trúc dự án

go-boilerplate/
├── cmd/
│   └── server/             # Application entry point
├── internal/
│   ├── api/                # API handlers (Checkout, Portal, Webhook)
│   ├── core/               # Configuration and system core
│   └── lib/                # Shared logic (Products, Customer utils)
├── templates/              # HTML templates
├── Makefile                # Build and run commands
├── go.mod                  # Go module definition
├── go.sum                  # Dependency checksums
├── .env.example            # Environment template
└── README.md

API Endpoints

Boilerplate bao gồm các điểm cuối được cấu hình sẵn sau:
Điểm cuốiPhương thứcMô tả
/GETTrang giá với danh sách sản phẩm
/api/checkoutPOSTTạo một phiên thanh toán mới
/api/webhookPOSTXử lý webhook Dodo Payments
/api/customer-portalPOSTTạo URL cổng khách hàng

Tùy chỉnh

Cập nhật thông tin sản phẩm

Chỉnh sửa internal/lib/products.go để sửa đổi:
  • ID sản phẩm (từ bảng điều khiển Dodo của bạn)
  • Giá cả
  • Tính năng
  • Mô tả
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",
        },
    },
}

Tự động điền dữ liệu khách hàng

Trong templates/index.html, thay thế dữ liệu khách hàng được mã hóa cứng bằng dữ liệu người dùng thực tế của bạn:
const customerData = {
    name: "John Doe",       // Replace with actual logged-in user's name
    email: "[email protected]"  // Replace with actual logged-in user's email
};
Trong một ứng dụng sản xuất, bạn sẽ tiêm động các giá trị này từ hệ thống xác thực của bạn.

Sự kiện Webhook

Boilerplate chứng minh việc xử lý các sự kiện webhook trong internal/api/webhook.go. Các sự kiện được hỗ trợ bao gồm:
Sự kiệnMô tả
subscription.activeKích hoạt khi một đăng ký trở nên hoạt động
payment.succeededKích hoạt khi một thanh toán thành công
Thêm logic kinh doanh của bạn bên trong trình xử lý webhook để:
  • Cập nhật quyền người dùng trong cơ sở dữ liệu của bạn
  • Gửi email xác nhận
  • Cung cấp quyền truy cập vào các sản phẩm kỹ thuật số
  • Theo dõi phân tích và số liệu

Kiểm tra Webhook Locally

Đối với phát triển cục bộ, sử dụng các công cụ như ngrok để mở rộng máy chủ cục bộ của bạn:
ngrok http 8000
Cập nhật URL webhook trong Bảng điều khiển Dodo Payments:
https://your-ngrok-url.ngrok.io/api/webhook

Triển khai

Xây dựng cho sản xuất

make build
Hoặc thủ công:
go build -o bin/server cmd/server/main.go
./bin/server

Triển khai lên Vercel

[ Triển khai với Vercel ](https://vercel.com/new/clone?repository-url=https://github.com/dodopayments/go-boilerplate)

Docker

Tạo một Dockerfile:
FROM golang:1.21-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"]
Xây dựng và chạy:
docker build -t go-dodo .
docker run -p 8000:8000 --env-file .env go-dodo

Cân nhắc sản xuất

Trước khi triển khai lên sản xuất:
  • Chuyển DODO_PAYMENTS_ENVIRONMENT sang live_mode
  • Sử dụng các khóa API sản xuất từ bảng điều khiển
  • Cập nhật URL webhook đến miền sản xuất của bạn
  • Bật HTTPS cho tất cả các điểm cuối

Khắc phục sự cố

Đảm bảo các mô-đun Go đã được tải đúng cách:
go mod tidy
go mod download
Nguyên nhân phổ biến:
  • ID sản phẩm không hợp lệ - xác minh nó tồn tại trong bảng điều khiển Dodo của bạn
  • Khóa API sai hoặc cài đặt môi trường trong .env
  • Kiểm tra nhật ký máy chủ để biết thông điệp lỗi chi tiết
Đối với kiểm tra cục bộ, sử dụng ngrok để mở rộng máy chủ của bạn:
ngrok http 8000
Cập nhật URL webhook trong bảng điều khiển Dodo đến URL ngrok. Hãy chắc chắn cập nhật tệp .env của bạn với khóa xác minh webhook chính xác.
Đảm bảo bạn đang chạy máy chủ từ thư mục gốc của dự án, hoặc rằng đường dẫn mẫu được cấu hình đúng trong mã của bạn.

Tìm hiểu thêm

Hỗ trợ

Cần giúp đỡ với boilerplate?