使用go-jsonerror生成遵循JsonApi规范的错误响应

go-jsonerror是一个用于生成符合JsonApi规范错误响应的Go语言库。JsonApi规范为错误响应定义了统一的结构，使得API客户端能够以标准化的方式处理错误。

安装

go get github.com/deliveroo/go-jsonerror

基本用法

创建简单错误

package main

import (
	"encoding/json"
	"fmt"
	"net/http"
	
	"github.com/deliveroo/go-jsonerror"
)

func main() {
	// 创建一个简单的错误
	err := jsonerror.New(
		http.StatusBadRequest,
		"invalid_parameter",
		"The 'email' parameter is invalid",
	)
	
	// 转换为JSON
	jsonData, _ := json.MarshalIndent(err, "", "  ")
	fmt.Println(string(jsonData))
}

输出:

{
  "errors": [
    {
      "status": "400",
      "code": "invalid_parameter",
      "title": "Bad Request",
      "detail": "The 'email' parameter is invalid"
    }
  ]
}

添加更多错误详情

err := jsonerror.New(
	http.StatusNotFound,
	"resource_not_found",
	"User with ID 123 not found",
).WithMeta(map[string]interface{}{
	"resource_id": "123",
	"resource_type": "user",
}).WithSource(&jsonerror.ErrorSource{
	Parameter: "id",
})

输出:

{
  "errors": [
    {
      "status": "404",
      "code": "resource_not_found",
      "title": "Not Found",
      "detail": "User with ID 123 not found",
      "source": {
        "parameter": "id"
      },
      "meta": {
        "resource_id": "123",
        "resource_type": "user"
      }
    }
  ]
}

在HTTP处理器中使用

func getUserHandler(w http.ResponseWriter, r *http.Request) {
	userID := r.URL.Query().Get("id")
	if userID == "" {
		err := jsonerror.New(
			http.StatusBadRequest,
			"missing_parameter",
			"The 'id' parameter is required",
		).WithSource(&jsonerror.ErrorSource{
			Parameter: "id",
		})
		
		w.Header().Set("Content-Type", "application/json")
		w.WriteHeader(err.Status)
		json.NewEncoder(w).Encode(err)
		return
	}
	
	// 正常处理逻辑...
}

创建多个错误的响应

errors := jsonerror.Errors{
	jsonerror.New(
		http.StatusBadRequest,
		"invalid_email",
		"The email format is invalid",
	).WithSource(&jsonerror.ErrorSource{
		Parameter: "email",
	}),
	jsonerror.New(
		http.StatusBadRequest,
		"invalid_password",
		"Password must be at least 8 characters",
	).WithSource(&jsonerror.ErrorSource{
		Parameter: "password",
	}),
}

w.Header().Set("Content-Type", "application/json")
w.WriteHeader(http.StatusBadRequest)
json.NewEncoder(w).Encode(errors)

输出:

{
  "errors": [
    {
      "status": "400",
      "code": "invalid_email",
      "title": "Bad Request",
      "detail": "The email format is invalid",
      "source": {
        "parameter": "email"
      }
    },
    {
      "status": "400",
      "code": "invalid_password",
      "title": "Bad Request",
      "detail": "Password must be at least 8 characters",
      "source": {
        "parameter": "password"
      }
    }
  ]
}

自定义错误

你还可以创建自定义的错误类型：

type CustomError struct {
	*jsonerror.Error
	CustomField string `json:"custom_field"`
}

func NewCustomError(status int, code, detail, customField string) *CustomError {
	return &CustomError{
		Error:       jsonerror.New(status, code, detail),
		CustomField: customField,
	}
}

// 使用
err := NewCustomError(
	http.StatusForbidden,
	"access_denied",
	"You don't have permission to access this resource",
	"additional_info",
)

jsonData, _ := json.MarshalIndent(err, "", "  ")
fmt.Println(string(jsonData))

输出:

{
  "errors": [
    {
      "status": "403",
      "code": "access_denied",
      "title": "Forbidden",
      "detail": "You don't have permission to access this resource",
      "custom_field": "additional_info"
    }
  ]
}

总结

go-jsonerror库提供了简单易用的方式来生成符合JsonApi规范的错误响应，主要特点包括：

1. 遵循JsonApi错误响应规范
2. 支持添加元数据(meta)和错误源(source)
3. 支持多个错误组合
4. 易于扩展自定义错误类型
5. 与标准net/http包无缝集成

通过使用这个库，你可以确保你的API错误响应保持一致性，客户端可以更容易地解析和处理错误。