S01L03 - 更多关于基于资源的 URI

html

掌握 RESTful API 链接：基于资源的 URI 设计指南
目录

介绍 .......................................................... 1  
理解基于文件的链接 ............. 3  
基于资源的链接 .................................. 5  
设计集合 URI .......................... 8  
实现基于过滤器的 URI ............... 12  
建立 URI 关系 ............... 16  
实际示例和代码 ..................... 20  
结论 ............................................................ 25  
补充信息 ....................... 27  


介绍
在不断发展的网页开发领域，设计直观且高效的 RESTful API 至关重要。API 设计的一个关键方面是构建既用户友好又可扩展的基于资源的 URI（统一资源标识符）。本电子书深入探讨了基于资源的链接创建原则，与传统的基于文件的链接进行对比，并为希望掌握 RESTful API 中 URI 设计的开发者提供了全面指南。
关键点：

RESTful API 中一致且基于资源的 URI 的重要性。
基于文件的链接与基于资源的链接之间的比较。
通过集合和基于过滤器的 URI 处理大型数据集的策略。
建立不同资源之间清晰的关系以优化 API 导航。


理解基于文件的链接
在深入探讨基于资源的链接之前，有必要了解在网页开发中常用的传统基于文件的链接方法。
什么是基于文件的链接？
基于文件的链接指的是直接指向服务器上特定文件的 URL。这些链接通常包含文件扩展名，结构简单，易于实现但在灵活性方面有限。
示例：

https://travel.com/cochin.html
https://travel.com/goa.html
https://travel.com/mumbai.html
https://travel.com/newyork.html
https://travel.com/vegas.html

基于文件的链接的优点

简洁：易于创建和理解。
直接访问：用户可以通过其 URL 直接访问特定页面。

基于文件的链接的缺点

可扩展性问题：管理大量静态文件变得繁琐。
灵活性有限：难以实现动态内容和过滤机制。
维护挑战：更新 URL 可能导致链接断裂，并需要大量更改。

比较表：基于文件的链接 vs. 基于资源的链接


特征
基于文件的链接
基于资源的链接


结构
带扩展名的直接文件路径
分层的、面向资源的 URI


可扩展性
随着资源增加可扩展性低
通过资源集合高度可扩展


灵活性
仅限于静态文件表示
支持动态查询和过滤


维护
更改后易导致链接断裂
通过一致的模式更易维护


示例 URI
travel.com/goa.html
travel.com/cities/goa



基于资源的链接
基于资源的链接是 RESTful API 设计的基础，强调以结构化和有意义的方式组织资源。
定义基于资源的链接
基于资源的链接使用名词来表示实体，确保每个 URI 明确标识特定资源或资源集合。这种方法遵循 REST 原则，促进一致性和可扩展性。
示例：

https://travel.com/cities/{city_id}

复数形式的重要性
使用复数名词（例如 cities 而不是 city）表示资源集合，便于过滤、分页和关系管理。
示例：

https://travel.com/cities - 列出所有城市。
https://travel.com/cities/1 - 获取 ID 为 1 的城市。

主要优点

一致性：统一的 URI 模式增强了可预测性。
可扩展性：高效管理大量资源集合。
灵活性：简化过滤和关系的实现。


设计集合 URI
集合 URI 代表一组资源，使客户端能够检索项目列表或应用批量操作。
集合 URI 的结构
集合 URI 通常使用资源名称的复数形式。这一设计选择符合 REST 约定，表示存在多个项目。
示例：

https://travel.com/cities - 代表所有城市的集合。

使用集合 URI 的好处

易于导航：用户可以轻松浏览集合并连接到单个资源。
高效的数据处理：简化分页和过滤机制的实现。
增强的组织：促进相似资源的逻辑分组。

实际实现
当访问集合 URI 时，服务器以结构化格式（如 JSON 或 XML）响应资源列表。
示例响应：




		
		
			
			
Java
			
			[
  {
    "id": 1,
    "name": "Kochi",
    "country": "India"
  },
  {
    "id": 2,
    "name": "Goa",
    "country": "India"
  },
  // 更多城市...
]
			
				
					
				
					1
2
3
4
5
6
7
8
9
10
11
12
13
				
						[
  {
    "id": 1,
    "name": "Kochi",
    "country": "India"
  },
  {
    "id": 2,
    "name": "Goa",
    "country": "India"
  },
  // 更多城市...
]
					
				
			
		


处理大型数据集的考虑因素
对于包含大量资源的集合，实施诸如分页等机制以高效管理数据至关重要。

实现基于过滤器的 URI
基于过滤器的 URI 允许客户端根据特定条件检索资源的子集，增强了 API 的灵活性和可用性。
理解 URI 中的过滤器
过滤器使客户端能够指定返回资源必须满足的条件。这在用户需要查找匹配某些属性的资源时尤为重要。
示例过滤器 URI：

https://travel.com/cities?startswith=M - 获取以 'M' 开头的城市。
https://travel.com/cities?offset=25&limit=50 - 获取第 25 到第 75 个城市。
https://travel.com/cities?startswith=M&limit=10 - 获取前 10 个以 'M' 开头的城市。

基于过滤器的 URI 的优点

目标数据检索：客户端可以精准获取所需数据，避免过度获取。
性能优化：通过限制处理和传输的数据量，减少服务器负载和响应时间。
增强用户体验：高效地向用户提供相关信息。

实现分页和限制
分页将大型数据集划分为可管理的块，而限制则限制单次响应中返回的资源数量。
示例：

Offset: 指定数据集中的起始点。
Limit: 定义要返回的最大资源数量。

URI 示例：

https://travel.com/cities?offset=25&limit=50

处理多个过滤器
API 应设计为支持同时使用多个过滤器，以允许复杂的查询和资源检索。
示例：

https://travel.com/cities?startswith=M&limit=10


建立 URI 关系
定义不同资源之间的清晰关系是构建一致且可导航的 API 结构的基础。
理解资源关系
资源关系描述了不同实体在 API 中的连接方式。例如，国家包含多个城市，建立了层级关系。
示例 URI：

https://travel.com/countries/india/cities - 列出印度的所有城市。
https://travel.com/countries/india/cities/1 - 获取印度中 ID 为 1 的城市。
https://travel.com/cities/1 - 获取 ID 为 1 的城市。

定义关系的好处

逻辑组织：以反映现实世界关系的方式结构化资源。
导航便利：客户端可以无缝遍历相关资源。
数据完整性：通过强制执行关系约束保持一致性。

URI 关系的最佳实践

一致的层级结构：保持清晰且一致的层级结构。
避免深度嵌套：限制嵌套资源的深度，以防止 URI 过于复杂。
重用资源：如有必要，通过多条路径访问资源，确保灵活性。


实际示例和代码
为了巩固讨论的概念，让我们通过实际示例和代码片段，展示如何在 Spring Boot 中设计基于资源的 URI 以实现 RESTful API。
示例场景
考虑一家旅游公司，travel.com，提供全球各地城市的信息。我们旨在设计基于资源的链接，以有效管理城市数据。
定义资源 URI




		
		
			
			
Java
			
			@RestController
@RequestMapping("/cities")
public class CityController {

    @GetMapping("/{id}")
    public ResponseEntity&lt;City&gt; getCity(@PathVariable int id) {
        City city = cityService.getCityById(id);
        return ResponseEntity.ok(city);
    }

    @GetMapping
    public ResponseEntity&lt;List&lt;City&gt;&gt; getAllCities(
            @RequestParam(required = false) String startswith,
            @RequestParam(defaultValue = "0") int offset,
            @RequestParam(defaultValue = "50") int limit) {
        List&lt;City&gt; cities = cityService.getCities(startswith, offset, limit);
        return ResponseEntity.ok(cities);
    }
}
			
				
					
				
					1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
				
						@RestController
@RequestMapping("/cities")
public class CityController {
 
    @GetMapping("/{id}")
    public ResponseEntity&lt;City&gt; getCity(@PathVariable int id) {
        City city = cityService.getCityById(id);
        return ResponseEntity.ok(city);
    }
 
    @GetMapping
    public ResponseEntity&lt;List&lt;City&gt;&gt; getAllCities(
            @RequestParam(required = false) String startswith,
            @RequestParam(defaultValue = "0") int offset,
            @RequestParam(defaultValue = "50") int limit) {
        List&lt;City&gt; cities = cityService.getCities(startswith, offset, limit);
        return ResponseEntity.ok(cities);
    }
}
					
				
			
		


语法解释

@RestController: 表明该类处理 RESTful 请求。
@RequestMapping("/cities"): 将 HTTP 请求映射到 /cities URI。
@GetMapping("/{id}"): 将 GET 请求映射到 /cities/{id} 以检索特定城市。
@GetMapping: 将 GET 请求映射到 /cities 以检索所有城市并可选过滤。
@RequestParam: 从 URI 中提取查询参数（startswith, offset, limit）。

逐步代码执行

检索特定城市：

URI: https://travel.com/cities/1
调用方法：getCity(1)
输出：返回 ID 为 1 的城市（例如，Kochi）。


检索所有城市：

URI: https://travel.com/cities
调用方法：getAllCities(null, 0, 50)
输出：返回前 50 个城市。


应用过滤器：

URI: https://travel.com/cities?startswith=M&limit=10
调用方法：getAllCities("M", 0, 10)
输出：返回前 10 个以 'M' 开头的城市。



演示关系




		
		
			
			
Java
			
			@RestController
@RequestMapping("/countries")
public class CountryController {

    @GetMapping("/{countryId}/cities")
    public ResponseEntity&lt;List&lt;City&gt;&gt; getCitiesByCountry(@PathVariable int countryId) {
        List&lt;City&gt; cities = cityService.getCitiesByCountryId(countryId);
        return ResponseEntity.ok(cities);
    }

    @GetMapping("/{countryId}/cities/{cityId}")
    public ResponseEntity&lt;City&gt; getCityInCountry(@PathVariable int countryId, @PathVariable int cityId) {
        City city = cityService.getCityInCountry(countryId, cityId);
        return ResponseEntity.ok(city);
    }
}
			
				
					
				
					1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
				
						@RestController
@RequestMapping("/countries")
public class CountryController {
 
    @GetMapping("/{countryId}/cities")
    public ResponseEntity&lt;List&lt;City&gt;&gt; getCitiesByCountry(@PathVariable int countryId) {
        List&lt;City&gt; cities = cityService.getCitiesByCountryId(countryId);
        return ResponseEntity.ok(cities);
    }
 
    @GetMapping("/{countryId}/cities/{cityId}")
    public ResponseEntity&lt;City&gt; getCityInCountry(@PathVariable int countryId, @PathVariable int cityId) {
        City city = cityService.getCityInCountry(countryId, cityId);
        return ResponseEntity.ok(city);
    }
}
					
				
			
		


解释

@GetMapping("/{countryId}/cities"): 检索特定国家内的所有城市。
@GetMapping("/{countryId}/cities/{cityId}"): 检索特定国家内的某个城市。

示例请求

印度的城市列表：

URI: https://travel.com/countries/1/cities
输出：列出印度的所有城市。


印度的特定城市：

URI: https://travel.com/countries/1/cities/2
输出：获取印度中 ID 为 2 的城市（例如，Mumbai）。




结论
设计基于资源的 URI 是有效 RESTful API 开发的基石。通过遵循一致的命名约定、使用复数形式表示集合、实现强大的过滤和分页机制，以及明确定义资源关系，开发者可以创建可扩展、可维护且用户友好的 API。采用这些最佳实践不仅提升了开发者的体验，还确保 API 能够无缝演进以满足不断增长的需求。
关键要点：

一致性至关重要：统一的 URI 结构简化了 API 的导航和使用。
通过设计实现可扩展性：复数形式的资源名称和集合 URI 高效支持大型数据集。
通过过滤器实现灵活性：实现强大的过滤和分页机制满足多样化的客户端需求。
清晰的关系增强导航：定义良好的资源关系促进了直观的 API 遍历。

通过掌握本电子书中概述的原则，开发者可以提升他们的 RESTful API 设计，确保其既稳健又适应未来的需求。
SEO 关键词：RESTful API, URI 设计, 基于资源的链接, API 开发, REST 原则, 集合 URI, 基于过滤器的 URI, API 分页, 资源关系, Spring Boot RESTful API

补充信息
详细比较表
表 1：基于文件的链接 vs. 基于资源的链接


特征
基于文件的链接
基于资源的链接


结构
带扩展名的直接文件路径
分层的、面向资源的 URI


可扩展性
随着资源增加可扩展性低
通过资源集合高度可扩展


灵活性
仅限于静态文件表示
支持动态查询和过滤


维护
更改后易导致链接断裂
通过一致的模式更易维护


示例 URI
travel.com/goa.html
travel.com/cities/goa


表 2：集合 URI 特征


特征
描述


复数形式
使用复数名词表示资源集合。


端点
简化对资源列表的访问。


分页
通过偏移量和限制参数管理大型数据集。


过滤
允许基于条件检索特定子集。


一致的模式
在不同资源类型间保持统一。


额外资源

RESTful API 设计最佳实践： 链接
Spring Boot 文档： 链接
理解 REST API 中的 URI 设计： 链接


注意：本文由 AI 生成。
特征	基于文件的链接	基于资源的链接
结构	带扩展名的直接文件路径	分层的、面向资源的 URI
可扩展性	随着资源增加可扩展性低	通过资源集合高度可扩展
灵活性	仅限于静态文件表示	支持动态查询和过滤
维护	更改后易导致链接断裂	通过一致的模式更易维护
示例 URI	travel.com/goa.html	travel.com/cities/goa
特征	描述
复数形式	使用复数名词表示资源集合。
端点	简化对资源列表的访问。
分页	通过偏移量和限制参数管理大型数据集。
过滤	允许基于条件检索特定子集。
一致的模式	在不同资源类型间保持统一。