GoLang解析结构不一致的第三方API JSON响应的最佳实践

针对第三方API返回结构随状态变化的场景，以下是几种兼顾类型安全和灵活性的实践方案：

1. 先解析公共字段，再动态分发到对应结构体 #

这是最常用的方案，核心思路是先解析所有响应都包含的公共字段（比如status），再根据字段值将原始响应反序列化到对应的结构体中，既保留类型安全，又能处理不同结构的响应。

示例代码： #

package main

import (
	"encoding/json"
	"fmt"
)

// 公共基础结构体，只包含所有响应都有的字段
type BaseResponse struct {
	Status string `json:"status"`
}

// 成功响应结构体
type SuccessResponse struct {
	BaseResponse
	DueDate string `json:"due_date"`
	Library string `json:"library"`
}

// 未授权错误响应
type UnauthorizedError struct {
	BaseResponse
	Error string `json:"error"`
}

// 资源不存在错误响应
type NotFoundError struct {
	BaseResponse
	ErrorDetails struct {
		Type string `json:"type"`
		File string `json:"file"`
	} `json:"error-details"`
}

func main() {
	// 模拟成功响应
	successResp := `{"status": "ok", "due_date": "2023-01-01", "library": "AIEHA1"}`
	// 模拟未授权响应
	unauthResp := `{"status": "unauthorized", "error": "Field Bearer empty"}`
	// 模拟未找到响应
	notFoundResp := `{"status": "not-found", "error-details": {"type": "file-not-found", "file": "/index"}}`

	handleResponse([]byte(successResp))
	handleResponse([]byte(unauthResp))
	handleResponse([]byte(notFoundResp))
}

func handleResponse(raw []byte) {
	var base BaseResponse
	if err := json.Unmarshal(raw, &base); err != nil {
		fmt.Printf("解析基础响应失败: %v\n", err)
		return
	}

	switch base.Status {
	case "ok":
		var success SuccessResponse
		if err := json.Unmarshal(raw, &success); err != nil {
			fmt.Printf("解析成功响应失败: %v\n", err)
			return
		}
		fmt.Printf("成功响应: 到期日=%s, 库ID=%s\n", success.DueDate, success.Library)
	case "unauthorized":
		var unauth UnauthorizedError
		if err := json.Unmarshal(raw, &unauth); err != nil {
			fmt.Printf("解析未授权响应失败: %v\n", err)
			return
		}
		fmt.Printf("未授权错误: %s\n", unauth.Error)
	case "not-found":
		var notFound NotFoundError
		if err := json.Unmarshal(raw, &notFound); err != nil {
			fmt.Printf("解析未找到响应失败: %v\n", err)
			return
		}
		fmt.Printf("未找到错误: 类型=%s, 文件=%s\n", notFound.ErrorDetails.Type, notFound.ErrorDetails.File)
	default:
		fmt.Printf("未知响应状态: %s\n", base.Status)
		// 兜底可以解析到map[string]interface{}处理
		var unknown map[string]interface{}
		if err := json.Unmarshal(raw, &unknown); err == nil {
			fmt.Printf("未知响应内容: %v\n", unknown)
		}
	}
}

2. 用包含所有字段的结构体+omitempty兼容多结构 #

如果API响应的字段差异不大，可以定义一个包含所有可能字段的结构体，通过omitempty标签忽略空值，解析后根据status判断哪些字段有效。这种方案适合字段数量不多的场景。

示例代码： #

package main

import (
	"encoding/json"
	"fmt"
)

type APIResponse struct {
	Status       string `json:"status"`
	DueDate      string `json:"due_date,omitempty"`
	Library      string `json:"library,omitempty"`
	Error        string `json:"error,omitempty"`
	ErrorDetails struct {
		Type string `json:"type,omitempty"`
		File string `json:"file,omitempty"`
	} `json:"error-details,omitempty"`
}

func main() {
	successResp := `{"status": "ok", "due_date": "2023-01-01", "library": "AIEHA1"}`
	var resp APIResponse
	if err := json.Unmarshal([]byte(successResp), &resp); err != nil {
		fmt.Printf("解析失败: %v\n", err)
		return
	}

	switch resp.Status {
	case "ok":
		fmt.Printf("成功: 到期日=%s, 库=%s\n", resp.DueDate, resp.Library)
	case "unauthorized":
		fmt.Printf("错误: %s\n", resp.Error)
	case "not-found":
		fmt.Printf("错误: 类型=%s, 文件=%s\n", resp.ErrorDetails.Type, resp.ErrorDetails.File)
	}
}

3. 结合json.RawMessage做灵活兜底 #

如果API的错误结构非常多样，无法提前枚举所有可能，可以先用结构体解析已知字段，将未知部分用json.RawMessage保留原始JSON数据，后续按需解析。这种方案兼顾类型安全和灵活性。

示例代码： #

package main

import (
	"encoding/json"
	"fmt"
)

type BaseResponse struct {
	Status string          `json:"status"`
	// 用RawMessage保留未定义的字段内容
	RawData json.RawMessage `json:"-"`
}

// 解析时先把整个响应存到RawData，再解析基础字段
func UnmarshalBaseResponse(raw []byte) (BaseResponse, error) {
	var base BaseResponse
	base.RawData = raw
	err := json.Unmarshal(raw, &base)
	return base, err
}

func main() {
	unknownErrResp := `{"status": "rate-limit", "limit": 100, "remaining": 0, "reset": 1690000000}`

	base, err := UnmarshalBaseResponse([]byte(unknownErrResp))
	if err != nil {
		fmt.Printf("解析失败: %v\n", err)
		return
	}

	if base.Status == "rate-limit" {
		// 按需解析RawData到临时结构体
		type RateLimitError struct {
			Limit     int `json:"limit"`
			Remaining int `json:"remaining"`
			Reset     int `json:"reset"`
		}
		var rateLimitErr RateLimitError
		if err := json.Unmarshal(base.RawData, &rateLimitErr); err == nil {
			fmt.Printf("限流错误: 限额=%d, 剩余=%d, 重置时间戳=%d\n", rateLimitErr.Limit, rateLimitErr.Remaining, rateLimitErr.Reset)
		}
	}
}

内容的提问来源于stack exchange，提问作者Melissia J