如何设计出更好的 API ？_如何设计一个良好的api，整理出Golang逆向系列学习进阶视频

最新推荐文章于 2024-09-25 07:15:00 发布

2401_84239525

最新推荐文章于 2024-09-25 07:15:00 发布

阅读量632

点赞数 18

分类专栏： 2024年程序员学习文章标签： golang 开发语言后端

本文链接：https://blog.csdn.net/2401_84239525/article/details/137980143

版权

2024年程序员学习专栏收录该内容

115 篇文章

订阅专栏

先自我介绍一下，小编浙江大学毕业，去过华为、字节跳动等大厂，目前阿里P7

深知大多数程序员，想要提升技能，往往是自己摸索成长，但自己不成体系的自学效果低效又漫长，而且极易碰到天花板技术停滞不前！

因此收集整理了一份《2024年最新Golang全套学习资料》，初衷也很简单，就是希望能够帮助到想自学提升又不知道该从何学起的朋友。

既有适合小白学习的零基础资料，也有适合3年以上经验的小伙伴深入学习提升的进阶课程，涵盖了95%以上Go语言开发知识点，真正体系化！

由于文件比较多，这里只是将部分目录截图出来，全套包含大厂面经、学习笔记、源码讲义、实战项目、大纲路线、讲解视频，并且后续会持续更新

如果你需要这些资料，可以添加V获取：vip1024b （备注go）

正文

“code”: “/register/password_required”",
“message”: “参数 [password] 是必须的！”
}

6、使用 `PATCH` 代替 `PUT`

如前所述，PATCH 请求应该对资源应用部分更新，而 PUT 完全替换现有资源。

允许任何字段不受任何限制地更新也是相当危险的；
我比较建议围绕 PATCH 做请求设计，因为：
当使用 PUT 只更新资源的一部分字段时，仍然需要传递整个资源，这使得它更加网络密集且容易出错；
根据我的经验，在实践中几乎不存在任何对资源进行完整更新有意义的用例。

7、使用分页

对所有返回资源集合并，使用相同响应结构的请求进行分页。例如 page size （或类似的）来控制要检索的块。

// Request => GET /home/v1/get-business-list?page=1&size=10&username=uiu

// Response <= 200 OK
{
“code”:200,
“message”:“success”,
“page”: 1,
“size”: 10,
“data”: [
// resources
],
“total_pages”: 20,
“has_previous_page”: false,
“has_next_page”: true
}

8、确保一致性

我知道这听起来好像是大家都知道的，但在实际执行过程中很难做到这一点。

好的 API 是可预测的，也就是说当调用者使用并理解这一个端口时，另一个端点最好也是以相同的方式工作。这样对于整个 API 很重要，也是衡量 API 是否设计良好和好用的关键指标之一。

对字段、资源和参数使用相同的大小写

对于中文转英文变量的命名工具, 你可以试试我开发的这个工具 varbook

使用复数或单数资源名称（我不在乎这个，但是我会统一名称）

/users/{id},/orders/{id} 或 /user/{id},/order/{id}

对所有端点使用相同的身份验证和授权方法
在 API 中使用相同的 HTTP 标头

例如 Api-Key 用于传递 API 密钥

根据响应类型使用相同的 HTTP 状态代码

例如当找不到资源时使用 404

对相同类型的操作使用相同的 HTTP 方法

例如 DELETE 删除资源时

9、对公共端点进行例外处理

默认情况下，每个端口都应该需要授权。大多数端口都需要调用经过身份验证的用户，因此将其设为默认值是有意义的。

如果需要公开调用端点，请显式设置此端口以允许未经授权的请求。

10、版本化 API

确保对 API 进行版本控制并在每个请求中传递版本，这样API的使用者就不会受到对另一个版本的任何更改的影响。

API 版本可以使用 HTTP 标头或查询/路径参数传递。即使是 API 的第一个版本（1.0）也应该明确地进行版本控制。

一个来自CSDN的不完整例子：

https://blog.csdn.net/community/home-api/v1/get-business-list?page=1&size=10…

11、使用合理的 HTTP 状态码

使用传统的 HTTP 状态代码来指示请求的成功或失败。不要使用太多，并在整个 API 中为相同的结果使用相同的状态代码。

一些例子：

200 取得普遍成功
201 为成功创作
400 对于来自客户端的错误请求
401 对于未经授权的请求
403 缺少权限
404 对于缺少的资源
429 对于太多的请求
5xx 对于内部错误（应不惜一切代价避免这些错误）

12、使用不言自明的命名

大多数端口都是面向资源的，应该使用不言自明的命名，不要添加可以从其他地方推断出的不必要的信息，这也适用于字段名称。

✅建议

GET /user => 检索用户
DELETE /user/{id} => 注销用户
POST /user/{id}/notifications => 为特定用户创建通知
user.nick_name

❌不建议

GET /getUser
POST /updateUser
POST /notification/user
user.NickName

13、返回创建的资源POST

建议在POST在使用请求创建资源后返回创建的资源。这一点很重要，因为返回的创建资源将反映底层数据源的当前状态，并将包含更新的信息（例如生成的 ID）。

// Request: POST /register
{
“email”: “uiuing@foxmail.com”,
“name”: “uiu”,
“web_site”:“uiuing.com”
}

// Response
{
“id”: “oVUdhmcFr0”,
“email”: “uiuing@foxmail.com”,
“name”: “uiu”,
“web_site”:“uiuing.com”
}

14、尽可能具体

如 12点 所述，在设计端口、命名字段以及决定接受哪些请求和响应时，我建议你尽可能具体。如果一个 PATCH 请求只接受两个字段 (name和password)，则不存在错误使用它而造成损坏数据的危险。

15、允许扩展资源

允许调用者使用名为 expand（或类似的）查询参数加载相关数据。这对于避免重复和一次性加载特定操作所需的所有数据特别有用。

// Request => GET /user/T9hoBuuTL4?expand=collect&expand=collect.items

// Response <= 200 OK
{
“id”: “oVUdhmcFr0”,
“email”: “uiuing@foxmail.com”,
“name”: “uiu”,
“web_site”:“uiuing.com”,
“collect”: [

{
“id”: “8161E0A4-0F5C-4A02-94A5-2880645A39E0”,
“items”: [
{
“name”: “如何设计出更好的 API ？”
},
{
“name”: “本地存储(Local Storage) 和会话存储(Session Storage)”
}
]
},
{
“id”: “23A7A17A-086A-4638-8EED-55E5CB580856”,
“items”: [
{
“name”: “【Jquery】入门、快速上手、DOM/Jquery对象之间互相转换”
}
]
}
]
]
}