S01L02 - 基于资源的URI

html

Resource-Based URIs: 全面指南

目录

简介
理解 Resource-Based URIs
基于动作的 URIs 与 Resource-Based URIs
设计有效的 Resource-Based URIs
Resource-Based URIs 中的 HTTP Methods
HTTP Status Codes 详解
实施 Resource-Based URIs：实际示例
最佳实践与惯例
结论


简介
在 Web 开发和 API 设计领域，Uniform Resource Identifiers (URIs) 在定义如何访问和操作资源方面发挥着关键作用。本电子书深入探讨 resource-based URIs，这是创建直观、可扩展和可维护的 RESTful APIs 的基本概念。
理解 resource-based URIs 对于旨在设计遵循最佳实践的 API 的开发人员至关重要，确保客户端和服务器之间通信的清晰性和效率。本指南将探讨基于动作和 resource-based URIs 之间的差异、HTTP Methods 的重要性、状态码，并提供实际示例以巩固您的理解。
Resource-Based URIs 的优缺点
优点：

清晰性：通过围绕资源结构化 URIs，增强了可读性和理解性。
可扩展性：促进 API 的更便捷的扩展和维护。
一致性：促进不同端点之间的统一性，使 API 更具可预测性。

缺点：

初始复杂性：可能需要对 REST 原则有更深入的理解。
刚性：严格遵守有时会限制某些场景下的灵活性。

比较概述



特征
基于动作的 URIs
Resource-Based URIs




结构
使用表示动作的动词（例如，/getBrands）
围绕资源中心化（例如，/brands）


可读性
由于使用不同的动作术语，可能会引起混淆
更直观，并围绕资源层次结构组织


REST 合规性
与 RESTful 原则不太一致
完全遵守 RESTful 标准


可扩展性
随着 API 增长可能会变得繁琐
易于扩展，资源管理清晰




第一章：理解 Resource-Based URIs
什么是 Resource-Based URIs？
Resource-Based URIs 是表示应用程序或服务中特定资源的端点。它们不关注动作或操作，而是围绕它们所代表的实体进行结构化，例如展厅中的 品牌、自行车 和 备件。
Resource-Based URIs 的重要性
采用 resource-based URIs 使您的 API 设计符合 RESTful 原则，促进扩展性、可维护性和清晰性。这种方法通过提供一种清晰一致的方式来访问和操作资源，简化了客户端和服务器之间的交互。
何时何地使用 Resource-Based URIs
Resource-based URIs 非常适合于：

RESTful APIs：确保遵守 REST 标准。
Microservices Architecture：促进模块化和可扩展的服务设计。
任何 API 设计：需要清晰性和可维护性为优先的地方。


第二章：基于动作的 URIs 与 Resource-Based URIs
基于动作的 URIs
基于动作的 URIs 包含动词以表示特定的动作或操作。例如：

/getBrands
/setBikes
/deleteSpare?id=25

虽然这种方法可行，但随着 API 的增长，往往会导致混淆和不一致。
Resource-Based URIs
Resource-Based URIs 关注所涉及的实体：

/brands
/brands/bajaj
/bikes/honda

这种结构增强了可读性，并符合 RESTful 的最佳实践。
比较分析



方面
基于动作的 URIs
Resource-Based URIs




动词使用
包含动作动词（get, set）
使用代表资源的名词


清晰性
不够直观
更直观且有组织性


REST 合规性
与 REST 原则不太一致
完全遵守 RESTful 标准


维护性
可能会变得繁琐
更易于维护和扩展




第三章：设计有效的 Resource-Based URIs
构建 URIs 的结构
有效的 resource-based URIs 遵循层级结构，表示资源之间的关系。例如：

/brands – 访问所有品牌。
/brands/bajaj – 访问特定品牌，Bajaj。
/bikes/honda – 访问 Honda 品牌下的所有自行车。
/spares/suzuki – 访问 Suzuki 相关的备件。
/spares/25 – 通过 ID 访问特定备件。

最佳实践

使用复数名词：以复数形式表示集合（例如，/brands）。
层级表示：通过 URI 结构反映资源之间的关系。
一致的命名约定：保持 URI 命名的一致性以提高可预测性。

实际示例
想象一个管理不同品牌、自行车和备件的展厅 API。一个设计良好的 resource-based URI 结构可能如下所示：




		
		
			
			
Java
			
			/brands
/brands/bajaj
/bikes
/bikes/honda
/spares
/spares/suzuki
/spares/25
			
				
					
				
					1
2
3
4
5
6
7
				
						/brands
/brands/bajaj
/bikes
/bikes/honda
/spares
/spares/suzuki
/spares/25
					
				
			
		



第四章：Resource-Based URIs 中的 HTTP Methods
HTTP Methods 概述
HTTP Methods 定义了可以在资源上执行的操作。在 RESTful APIs 中，最常用的方法包括：

GET：检索信息。
POST：创建新资源。
PUT：更新现有资源。
DELETE：移除资源。

详细解释

GET：用于从资源中获取数据。例如，GET /brands 检索所有品牌。
POST：用于创建新资源。例如，POST /brands 添加一个新品牌。
PUT：用于更新现有资源。例如，PUT /brands/bajaj 更新 Bajaj 品牌信息。
DELETE：用于删除资源。例如，DELETE /spares/25 移除 ID 为 25 的备件。

方法与操作的对应关系



HTTP 方法
操作
示例 URI




GET
检索资源
/brands


POST
创建新资源
/brands


PUT
更新现有资源
/brands/bajaj


DELETE
删除资源
/spares/25




第五章：HTTP Status Codes 详解
状态码的重要性
HTTP 状态码用于向服务器传达客户端请求的结果。它们提供了操作是否成功或是否发生错误的关键信息。
常见状态码

200 OK：请求成功。
201 Created：成功创建了一个新资源。
404 Not Found：请求的资源不存在。
500 Internal Server Error：服务器发生通用错误。

状态码分类



类别
代码范围
描述




1xx
100-199
信息性响应


2xx
200-299
成功响应


3xx
300-399
重定向消息


4xx
400-499
客户端错误响应


5xx
500-599
服务器错误响应



实际应用
当客户端发送 GET /brands 请求时，成功检索将返回 200 OK 状态。尝试使用 GET /spares/999 访问不存在的备件将导致 404 Not Found 状态。

第六章：实施 Resource-Based URIs：实际示例
场景：展厅 API
让我们考虑一个管理品牌、自行车和备件的展厅。我们将实施 Resource-Based URIs 来处理这些实体。
示例 URIs
品牌：

GET /brands – 检索所有品牌。
GET /brands/bajaj – 检索有关 Bajaj 的信息。
POST /brands – 添加一个新品牌。
PUT /brands/bajaj – 更新 Bajaj 的信息。
DELETE /brands/bajaj – 从系统中移除 Bajaj。

自行车：

GET /bikes – 检索所有自行车。
GET /bikes/honda – 检索 Honda 的自行车。
POST /bikes – 添加一辆新自行车。
PUT /bikes/honda – 更新 Honda 自行车的信息。
DELETE /bikes/honda – 移除 Honda 自行车。

备件：

GET /spares – 检索所有备件。
GET /spares/suzuki – 检索 Suzuki 的备件。
GET /spares/25 – 检索 ID 为 25 的备件。
POST /spares – 添加一个新备件。
PUT /spares/25 – 更新 ID 为 25 的备件。
DELETE /spares/25 – 移除 ID 为 25 的备件。

示例代码实现
以下是使用 Node.js 和 Express 实现管理品牌的 resource-based URIs 的简单示例。




		
		
			
			
Java
			
			const express = require('express');
const app = express();
app.use(express.json());

let brands = [
  { id: 1, name: 'Bajaj' },
  { id: 2, name: 'Honda' },
];

// Get all brands
app.get('/brands', (req, res) => {
  res.status(200).json(brands);
});

// Get a specific brand
app.get('/brands/:name', (req, res) => {
  const brand = brands.find(b => b.name.toLowerCase() === req.params.name.toLowerCase());
  if (!brand) return res.status(404).send('Brand not found');
  res.status(200).json(brand);
});

// Add a new brand
app.post('/brands', (req, res) => {
  const newBrand = {
    id: brands.length + 1,
    name: req.body.name,
  };
  brands.push(newBrand);
  res.status(201).json(newBrand);
});

// Update a brand
app.put('/brands/:name', (req, res) => {
  const brand = brands.find(b => b.name.toLowerCase() === req.params.name.toLowerCase());
  if (!brand) return res.status(404).send('Brand not found');
  brand.name = req.body.name;
  res.status(200).json(brand);
});

// Delete a brand
app.delete('/brands/:name', (req, res) => {
  const brandIndex = brands.findIndex(b => b.name.toLowerCase() === req.params.name.toLowerCase());
  if (brandIndex === -1) return res.status(404).send('Brand not found');
  const deletedBrand = brands.splice(brandIndex, 1);
  res.status(200).json(deletedBrand);
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, () => console.log(`Server running on port ${PORT}`));
			
				
					
				
					1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
				
						const express = require('express');
const app = express();
app.use(express.json());
 
let brands = [
  { id: 1, name: 'Bajaj' },
  { id: 2, name: 'Honda' },
];
 
// Get all brands
app.get('/brands', (req, res) => {
  res.status(200).json(brands);
});
 
// Get a specific brand
app.get('/brands/:name', (req, res) => {
  const brand = brands.find(b => b.name.toLowerCase() === req.params.name.toLowerCase());
  if (!brand) return res.status(404).send('Brand not found');
  res.status(200).json(brand);
});
 
// Add a new brand
app.post('/brands', (req, res) => {
  const newBrand = {
    id: brands.length + 1,
    name: req.body.name,
  };
  brands.push(newBrand);
  res.status(201).json(newBrand);
});
 
// Update a brand
app.put('/brands/:name', (req, res) => {
  const brand = brands.find(b => b.name.toLowerCase() === req.params.name.toLowerCase());
  if (!brand) return res.status(404).send('Brand not found');
  brand.name = req.body.name;
  res.status(200).json(brand);
});
 
// Delete a brand
app.delete('/brands/:name', (req, res) => {
  const brandIndex = brands.findIndex(b => b.name.toLowerCase() === req.params.name.toLowerCase());
  if (brandIndex === -1) return res.status(404).send('Brand not found');
  const deletedBrand = brands.splice(brandIndex, 1);
  res.status(200).json(deletedBrand);
});
 
const PORT = process.env.PORT || 3000;
app.listen(PORT, () => console.log(`Server running on port ${PORT}`));
					
				
			
		


代码解释

设置：我们初始化了一个 Express 应用程序并定义了一个示例 brands 数组。
GET /brands：检索所有品牌列表，响应状态为 200 OK。
GET /brands/:name：通过名称获取特定品牌。如果未找到，则返回 404 Not Found。
POST /brands：向集合中添加一个新品牌，响应状态为 201 Created。
PUT /brands/:name：更新现有品牌的名称。如果品牌不存在，则返回 404 Not Found。
DELETE /brands/:name：从集合中移除品牌。如果未找到该品牌，则返回 404 Not Found。

输出示例
请求： GET /brands
响应：




		
		
			
			
Java
			
			[
  { "id": 1, "name": "Bajaj" },
  { "id": 2, "name": "Honda" }
]
			
				
					
				
					1
2
3
4
				
						[
  { "id": 1, "name": "Bajaj" },
  { "id": 2, "name": "Honda" }
]
					
				
			
		



第七章：最佳实践与惯例
一致的命名
使用复数名词表示资源名称以代表集合。例如，使用 /brands 而不是 /brand。
层级结构
通过 URI 结构反映资源之间的关系。嵌套资源应逻辑地表示其层级关系。
HTTP 方法的使用
利用适当的 HTTP 方法对资源执行操作，确保遵守 RESTful 原则。
版本控制
在 URI 中实施版本控制，以便随着时间的推移管理更改而不干扰现有客户端。例如：




		
		
			
			
Java
			
			/v1/brands
/v2/brands
			
				
					
				
					1
2
				
						/v1/brands
/v2/brands
					
				
			
		


错误处理
提供有意义的错误消息和适当的 HTTP 状态码，帮助客户端理解其请求的结果。
文档
维护全面的 API 文档，详细说明可用的端点、方法、参数和预期响应。

结论
Resource-based URIs 是 RESTful API 设计的基石，提供了一种结构化且直观的管理资源的方法。通过关注实体而非动作，开发人员可以创建可扩展、可维护且易于客户端理解的 API。
在 URI 设计中采用最佳实践，适当使用 HTTP 方法，以及有效的错误处理，确保您的 API 不仅满足当前需求，而且能够适应未来的需求。无论您是在构建一个简单的应用程序还是一个复杂的微服务架构，resource-based URIs 都为稳健高效的 API 开发提供了基础。
注意：本文为 AI 生成。
HTTP 方法	操作	示例 URI
GET	检索资源	/brands
POST	创建新资源	/brands
PUT	更新现有资源	/brands/bajaj
DELETE	删除资源	/spares/25
特征	基于动作的 URIs	Resource-Based URIs
结构	使用表示动作的动词（例如，/getBrands）	围绕资源中心化（例如，/brands）
可读性	由于使用不同的动作术语，可能会引起混淆	更直观，并围绕资源层次结构组织
REST 合规性	与 RESTful 原则不太一致	完全遵守 RESTful 标准
可扩展性	随着 API 增长可能会变得繁琐	易于扩展，资源管理清晰
方面	基于动作的 URIs	Resource-Based URIs
动词使用	包含动作动词（get, set）	使用代表资源的名词
清晰性	不够直观	更直观且有组织性
REST 合规性	与 REST 原则不太一致	完全遵守 RESTful 标准
维护性	可能会变得繁琐	更易于维护和扩展
类别	代码范围	描述
1xx	100-199	信息性响应
2xx	200-299	成功响应
3xx	300-399	重定向消息
4xx	400-499	客户端错误响应
5xx	500-599	服务器错误响应