通过错误、JSON 和状态码理解 API

Source: Dev.to

引言

我曾开玩笑说 API 就像派对上的内向者：你永远不知道它们会回应还是完全忽视你。当我刚开始学习它们时，简直是一片黑暗。

随着时间的推移，我逐渐进步。我学会了 GET 和 POST 请求的工作原理，学会了如何在 JSON 中处理错误，以及为什么发送正确的 HTTP 状态码很重要。这些看似微小，却能让你的 API 变得可预测、专业且对使用者友好。

关键教训

GET 与 POST

• GET 用于检索数据。
• POST 用于发送数据。

正确使用它们是任何 API 的基础。

错误处理

在 JSON 中提供清晰的错误信息，帮助客户端了解出了什么问题以及如何修复。

状态码很重要

使用正确的 HTTP 状态码可以在不查看响应体的情况下传达请求的结果。示例：

• 200 OK – 请求成功
• 400 Bad Request – 客户端发送了无效数据
• 401 Unauthorized – 需要身份验证或验证失败

Go 示例

一个小的 Go 程序，接受用户的姓名并返回个性化的问候：

package main

import (
    "encoding/json"
    "net/http"
)

type User struct {
    Name string `json:"name"`
}

func greetHandler(w http.ResponseWriter, r *http.Request) {
    if r.Method != http.MethodPost {
        w.WriteHeader(http.StatusMethodNotAllowed)
        return
    }

    var user User
    decoder := json.NewDecoder(r.Body)
    if err := decoder.Decode(&user); err != nil {
        w.WriteHeader(http.StatusBadRequest)
        json.NewEncoder(w).Encode(map[string]string{"error": "Invalid JSON"})
        return
    }

    w.WriteHeader(http.StatusOK)
    json.NewEncoder(w).Encode(map[string]string{"message": "Hello " + user.Name})
}

func main() {
    http.HandleFunc("/greet", greetHandler)
    http.ListenAndServe(":8080", nil)
}

测试 API

使用 curl

curl -X POST http://localhost:8080/greet \
     -H "Content-Type: application/json" \
     -d '{"name":"Charity"}'

响应

{"message":"Hello Charity"}

使用 Postman

1. 打开 Postman 并创建一个新的 POST 请求。
2. 将 URL 设置为 http://localhost:8080/greet。
3. 在 Body 中，选择 raw → JSON 并输入：

{"name":"Charity"}

4. 发送请求；你将看到返回的问候语。

结论

即使是这个简单的示例也再次强调了正确的 JSON 格式、错误处理和状态码的重要性。这样的细微改进可以让 API 更易于使用和理解，把曾经让人望而生畏的东西转变为你可以自信构建的工具。

API 起初可能看起来像内向者，但一旦你学会它们的语言，它们其实相当友好。