RESTful风格接口设计

news/2024/10/14 4:29:30

我们平常开发一般只使用GET、POST方法。而对于HTTP给出的PUT、DELETE等其他方法都没使用。以RESTful风格设计接口就能全部用上这些方法。

按照RESTful理查德森成熟度模型改造接口

这个模型跟数据库范式等级相似，都是一层一层满足。我们的mvc接口不好说是哪一级，一般都是每个操作一个相当于一个资源。
但.ashx一般处理程序我们平时使用都是是第0级的，总共就一个接口，然后加各种参数，后端判断跳转，使用就特别繁琐。只是满足的不是很标准。
其等级如下

级别 0：单一 URI（Single URI）：

所有 API 请求都发送到同一个 URI。
使用 HTTP 动词来区分不同的操作，例如使用 POST 来创建资源，GET 来读取资源，PUT 来更新资源，DELETE 来删除资源。
这种级别的 API 没有使用 RESTful 架构的优势，与传统的 RPC 风格相似。

级别 1：每个资源一个 URI（One URI per resource）：

对于不同的资源，使用不同的 URI。
仍然使用 HTTP 动词来执行操作，但每个资源都有自己的 URI。
这种级别的 API 更符合 RESTful 架构的思想，但还没有完全利用 HTTP 的特性。

级别 2：每个资源一个 URI 和标准 HTTP 方法（One URI per resource with standard HTTP methods）：

每个资源有自己的 URI，并且使用标准的 HTTP 方法来执行操作。
使用 GET 来读取资源，POST 来创建资源，PUT 或 PATCH 来更新资源，DELETE 来删除资源。
这种级别的 API 开始充分利用了 HTTP 协议的特性，使得 API 更具表现力和可扩展性。

级别 3：使用超媒体（HATEOAS）（Hypermedia as the Engine of Application State）：

API 响应中包含了超媒体链接，使得客户端能够动态地发现和使用 API 中的资源。
客户端可以通过响应中的链接来导航和操作资源，而不需要依赖于固定的 API 结构。
这种级别的 API 是最符合 RESTful 架构的，提供了最大的灵活性和可发现性。

RESTful风格的一些要点

资源不包含动词
资源使用复数
资源唯一标识
对于第一点，一般都是使用路由模板。路由名称和方法名称分离。
对于第三点，使用路由参数代替查询字符串

第二级别接口

[AllowAnonymous]
[ApiController]
[Route("persons")]
public class RESTfulUserController : Controller
{private List<Person> _persons = new List<Person>(){new Person() { Id = 1, Name = "John", Age = 30 },new Person() { Id = 2, Name = "Alice", Age = 25 },new Person() { Id = 3, Name = "Bob", Age = 35 }};[HttpGet("")]public ActionResult GetPersons(){return Ok(_persons);}//{id}是一个占位符，用于表示在 URL 中传递的参数，叫做路由参数。也表示特定资源的标识符，通常是资源的唯一标识符。需与形参一致//Name字段用于为路由命名，别名的意思，通常与 CreatedAtRoute 或 Url.Action,Url.RouteUrl 等方法结合使用，以便在代码中引用具体的路由//nameof(生成字符串"GetPersons")// GET api/persons/{id}[HttpGet("{id}",Name =nameof(GetPerson))]public ActionResult GetPerson(int id){var person = _persons.FirstOrDefault(p => p.Id == id);if (person == null){return NotFound();}return Ok(person);}//多条件查询reastful风格应单独做成资源，不使用路由参数资源化[HttpGet("search")]public ActionResult SearchPerson(string? name,int? age){var searchperson = _persons;if (!string.IsNullOrEmpty(name))searchperson= searchperson.Where(p => p.Name == name).ToList();if (age.HasValue){searchperson = searchperson.Where(r => r.Age == age).ToList();}if (searchperson.Count==0){return NotFound();}return Ok(searchperson);}// POST api/persons[HttpPost("")]public ActionResult CreatePerson(Person person){person.Id = _persons.Count + 1;_persons.Add(person);//返回201表示资源已创建，并且在location标头中设置资源地址//第二个参数表示查询参数，如果该路由具有具有参数，则会将查询参数转化为路由参数，比如persons?id=1=?persons/1return CreatedAtRoute(nameof(GetPerson), new { id = person.Id }, person);}// PUT api/persons/{id}[HttpPut("{id}")]public ActionResult UpdatePerson(int id, Person person){var existingPerson = _persons.FirstOrDefault(p => p.Id == id);if (existingPerson == null){return NotFound();}existingPerson.Name = person.Name;existingPerson.Age = person.Age;return Ok(existingPerson);}// DELETE api/persons/{id}[HttpDelete("{id}")]public ActionResult DeletePerson(int id){var person = _persons.FirstOrDefault(p => p.Id == id);if (person == null){return NotFound();}_persons.Remove(person);//返回204表示操作成功，并且资源已不存在return StatusCode((int)System.Net.HttpStatusCode.NoContent);}
}public class Person
{public int Id { get; set; }public string Name { get; set; }public int Age { get; set; }
}

现在每个person都成为一个资源，有了自己的路径，并且对person的操作换为了相应的操作码，而不是都是get、post

第三级别接口

这一级的要求是资源的自描述，比如每一个资源要包含它能够接受的操作。我使用RiskFirst.Hateoas包来实现。

首先引用这个包
然后添加服务

//添加restful hateoas服务
builder.Services.AddLinks(config =>
{//给person资源增加hateoasconfig.AddPolicy<Person>(policy =>{policy.RequireSelfLink();//第一个参数代表一个link的字段名，第二个参数是路由名称，由http特性的Name字段配置，参三个字段是路由参数policy.RequireRoutedLink("update", nameof(RESTfulUserController.UpdatePerson), x => new { id = x.Id });policy.RequireRoutedLink("delete", nameof(RESTfulUserController.DeletePerson), x => new { id = x.Id });policy.RequireRoutedLink("all", nameof(RESTfulUserController.GetPersons));});//给persons资源增加hateoasconfig.AddPolicy<ItemsLinkContainer<Person>>(policy =>{policy.RequireSelfLink().RequireRoutedLink("search", nameof(RESTfulUserController.SearchPerson), x => new { Name = "name", Age = 0 }).RequireRoutedLink("create", nameof(RESTfulUserController.CreatePerson));});
});

最后改造资源
主要是为返回的实体添加继承Person:LinkContainer
注入hateoas服务ILinksService linksService到控制器中
调用await LinksService.AddLinksAsync(person);处理实体

第三级实现

[AllowAnonymous]
[ApiController]
[Route("persons")]
public class RESTfulUserController : Controller
{private List<Person> _persons = new List<Person>(){new Person() { Id = 1, Name = "John", Age = 30 },new Person() { Id = 2, Name = "Alice", Age = 25 },new Person() { Id = 3, Name = "Bob", Age = 35 }};public ILinksService LinksService { get; }public RESTfulUserController(ILinksService linksService){LinksService = linksService;}[HttpGet("",Name =nameof(GetPersons))]public async Task<ActionResult> GetPersons(){_persons.ForEach(async p => await LinksService.AddLinksAsync(p));var result = new ItemsLinkContainer<Person>() { Items = _persons };await LinksService.AddLinksAsync(result);return Ok(result);}//{id}是一个占位符，用于表示在 URL 中传递的参数，叫做路由参数。也表示特定资源的标识符，通常是资源的唯一标识符。需与形参一致//Name字段用于为路由命名，别名的意思，通常与 CreatedAtRoute 或 Url.Action,Url.RouteUrl 等方法结合使用，以便在代码中引用具体的路由//nameof(生成字符串"GetPerson")// GET api/persons/{id}[HttpGet("{id}",Name =nameof(GetPerson))]public async Task<ActionResult> GetPerson(int id){var person = _persons.FirstOrDefault(p => p.Id == id);await LinksService.AddLinksAsync(person);if (person == null){return NotFound();}return Ok(person);}//多条件查询reastful风格应单独做成资源，不使用路由参数资源化[HttpGet("search",Name =nameof(SearchPerson))]public ActionResult SearchPerson(string? name,int? age){var searchperson = _persons;if (!string.IsNullOrEmpty(name))searchperson= searchperson.Where(p => p.Name == name).ToList();if (age.HasValue){searchperson = searchperson.Where(r => r.Age == age).ToList();}if (searchperson.Count==0){return NotFound();}return Ok(searchperson);}// POST api/persons[HttpPost("",Name =nameof(CreatePerson))]public ActionResult CreatePerson(Person person){person.Id = _persons.Count + 1;_persons.Add(person);//返回201表示资源已创建，并且在location标头中设置资源地址//第二个参数表示查询参数，如果该路由具有具有参数，则会将查询参数转化为路由参数，比如persons?id=1=?persons/1return CreatedAtRoute(nameof(GetPerson), new { id = person.Id }, person);}// PUT api/persons/{id}[HttpPut("{id}",Name =nameof(UpdatePerson))]public ActionResult UpdatePerson(int id, Person person){var existingPerson = _persons.FirstOrDefault(p => p.Id == id);if (existingPerson == null){return NotFound();}existingPerson.Name = person.Name;existingPerson.Age = person.Age;return Ok(existingPerson);}// DELETE api/persons/{id}[HttpDelete("{id}",Name =nameof(DeletePerson))]public ActionResult DeletePerson(int id){var person = _persons.FirstOrDefault(p => p.Id == id);if (person == null){return NotFound();}_persons.Remove(person);//返回204表示操作成功，并且资源已不存在return StatusCode((int)System.Net.HttpStatusCode.NoContent);}
}public class Person:LinkContainer
{public int Id { get; set; }public string Name { get; set; }public int Age { get; set; }
}

persons资源返回结果是这样子的,对每个资源增加了links字段。

/person

{"items": [{"id": 1,"name": "John","age": 30,"links": {"self": {"rel": "RESTfulUser/GetPersons","href": "http://localhost:5234/persons","method": "GET"},"update": {"rel": "RESTfulUser/UpdatePerson","href": "http://localhost:5234/persons/1","method": "PUT"},"delete": {"rel": "RESTfulUser/DeletePerson","href": "http://localhost:5234/persons/1","method": "DELETE"},"all": {"rel": "RESTfulUser/GetPersons","href": "http://localhost:5234/persons","method": "GET"}}},{"id": 2,"name": "Alice","age": 25,"links": {"self": {"rel": "RESTfulUser/GetPersons","href": "http://localhost:5234/persons","method": "GET"},"update": {"rel": "RESTfulUser/UpdatePerson","href": "http://localhost:5234/persons/2","method": "PUT"},"delete": {"rel": "RESTfulUser/DeletePerson","href": "http://localhost:5234/persons/2","method": "DELETE"},"all": {"rel": "RESTfulUser/GetPersons","href": "http://localhost:5234/persons","method": "GET"}}},{"id": 3,"name": "Bob","age": 35,"links": {"self": {"rel": "RESTfulUser/GetPersons","href": "http://localhost:5234/persons","method": "GET"},"update": {"rel": "RESTfulUser/UpdatePerson","href": "http://localhost:5234/persons/3","method": "PUT"},"delete": {"rel": "RESTfulUser/DeletePerson","href": "http://localhost:5234/persons/3","method": "DELETE"},"all": {"rel": "RESTfulUser/GetPersons","href": "http://localhost:5234/persons","method": "GET"}}}],"links": {"self": {"rel": "RESTfulUser/GetPersons","href": "http://localhost:5234/persons","method": "GET"},"search": {"rel": "RESTfulUser/SearchPerson","href": "http://localhost:5234/persons/search?Name=name&Age=0","method": "GET"},"create": {"rel": "RESTfulUser/CreatePerson","href": "http://localhost:5234/persons","method": "POST"}}
}

本文来自互联网用户投稿，该文观点仅代表作者本人，不代表本站立场。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。如若转载，请注明出处：http://www.ryyt.cn/news/26835.html

如若内容造成侵权/违法违规/事实不符，请联系我们进行投诉反馈，一经查实，立即删除！