使用go-problemdetails处理HTTP问题详情

go-problemdetails是一个用于处理HTTP问题详情(RFC 7807)的Golang库，它提供了一种标准化的方式来表示HTTP API中的错误信息。下面我将详细介绍如何使用这个库。

安装

首先安装go-problemdetails库：

go get github.com/StevenACoffman/go-problemdetails

基本用法

1. 创建问题详情响应

package main

import (
	"net/http"

	"github.com/StevenACoffman/go-problemdetails"
)

func main() {
	http.HandleFunc("/example", func(w http.ResponseWriter, r *http.Request) {
		// 创建一个问题详情响应
		detail := problemdetails.NewProblem(
			"https://example.com/probs/out-of-credit",
			"You do not have enough credit.",
			"Your current balance is 30, but that costs 50.",
			http.StatusForbidden,
		)
		
		// 可选：添加自定义字段
		detail.With("balance", 30).
			With("accounts", []string{"/account/12345", "/account/67890"})
		
		// 发送响应
		problemdetails.ServeProblem(w, r, detail)
	})

	http.ListenAndServe(":8080", nil)
}

2. 使用预定义的问题类型

func handler(w http.ResponseWriter, r *http.Request) {
    // 使用预定义的问题类型
    detail := problemdetails.NewStatusProblem(http.StatusNotFound)
    problemdetails.ServeProblem(w, r, detail)
}

3. 自定义中间件处理错误

func ProblemDetailsMiddleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        defer func() {
            if err := recover(); err != nil {
                var detail *problemdetails.Problem
                
                switch e := err.(type) {
                case *problemdetails.Problem:
                    detail = e
                case error:
                    detail = problemdetails.NewStatusProblem(http.StatusInternalServerError).
                        With("error", e.Error())
                default:
                    detail = problemdetails.NewStatusProblem(http.StatusInternalServerError)
                }
                
                problemdetails.ServeProblem(w, r, detail)
            }
        }()
        
        next.ServeHTTP(w, r)
    })
}

高级用法

1. 自定义问题类型

// 定义自定义问题类型
var InsufficientCreditProblem = problemdetails.NewProblemType(
    "https://example.com/probs/insufficient-credit",
    "Insufficient Credit",
)

func creditHandler(w http.ResponseWriter, r *http.Request) {
    detail := problemdetails.NewProblemFromType(
        InsufficientCreditProblem,
        "Your credit balance is too low",
        "Current balance: 30, required: 50",
        http.StatusForbidden,
    ).With("balance", 30).With("required", 50)
    
    problemdetails.ServeProblem(w, r, detail)
}

2. 与标准库错误集成

func someOperation() error {
    return problemdetails.NewStatusProblem(http.StatusBadRequest).
        With("details", "Invalid input parameter").
        With("field", "username")
}

func handler(w http.ResponseWriter, r *http.Request) {
    if err := someOperation(); err != nil {
        if pd, ok := err.(*problemdetails.Problem); ok {
            problemdetails.ServeProblem(w, r, pd)
            return
        }
        // 处理其他类型的错误
    }
    // 正常处理
}

3. 从错误中提取问题详情

func extractProblemDetails(err error) *problemdetails.Problem {
    if pd, ok := err.(*problemdetails.Problem); ok {
        return pd
    }
    return problemdetails.NewStatusProblem(http.StatusInternalServerError).
        With("error", err.Error())
}

响应示例

使用上述代码生成的响应如下：

{
  "type": "https://example.com/probs/out-of-credit",
  "title": "You do not have enough credit.",
  "detail": "Your current balance is 30, but that costs 50.",
  "status": 403,
  "balance": 30,
  "accounts": [
    "/account/12345",
    "/account/67890"
  ]
}

最佳实践

1. 使用标准问题类型：尽可能使用预定义的标准问题类型
2. 包含足够信息：提供足够的信息帮助客户端理解问题
3. 保持一致性：在整个API中保持一致的错误格式
4. 适当的状态码：使用正确的HTTP状态码
5. 文档化：在API文档中记录可能返回的问题类型

go-problemdetails库提供了一种符合RFC 7807标准的方式来处理HTTP API中的错误，使客户端能够以一致的方式理解和处理错误情况。