.NET 6开发TodoList应用之实现API版本控制

目录
  • 需求
  • 目标
  • 原理与思路
  • 实现
    • 添加Nuget Package并配置服务
    • 实现API版本控制
  • 一点扩展
  • 总结

需求

API接口版本管理，对于一些规模稍大的企业应用来说，是经常需要关注的一大需求。尽管我们的示例程序TodoList很简单，但是我们也可以通过这个应用程序，来实践一下如何管理API接口版本。

目标

实现API接口版本管理。

原理与思路

要实现API版本管理，我们需要这个库：Microsoft.AspNetCore.Mvc.Versioning。它提供了.NET Web项目接口的版本管理功能。

实现

添加Nuget Package并配置服务

向Api项目中添加Microsoft.AspNetCore.Mvc.Versioning包。并添加一个扩展方法：

ApiServiceExtensions.cs

using Microsoft.AspNetCore.Mvc;

namespace TodoList.Api.Extensions;

public static class ApiServiceExtensions
{
    public static void ConfigureApiVersioning(this IServiceCollection services)
    {
        services.AddApiVersioning(options =>
        {
            // 向响应头中添加API版本信息
            options.ReportApiVersions = true;
            // 如果客户端不显式指定API版本，则使用默认版本
            options.AssumeDefaultVersionWhenUnspecified = true;
            // 配置默认版本为1.0
            options.DefaultApiVersion = new ApiVersion(1, 0);
        });
    }
}

在Program中调用：

Program.cs

// 省略其他...
builder.ConfigureLog();
builder.Services.ConfigureApiVersioning();

实现API版本控制

方法1: 添加ApiVersion属性

我们复制一份TodoItemController到新文件TodoItemV2Controller并修改类名和构造函数，其他保持原样。为了给Controller标记对应的API版本号，我们分别向两个Controller上添加属性：

[ApiVersion("2.0")]
[Route("/todo-item")]
[ApiController]
public class TodoItemV2Controller : ControllerBase
{
    private readonly IMediator _mediator;
    // 省略其他...
}

以及

[ApiVersion("1.0")]
[Route("/todo-item")]
[ApiController]
public class TodoItemController : ControllerBase
{
    private readonly IMediator _mediator;
    // 省略其他..
}

验证1: 请求中不添加任何API版本相关字段

启动Api项目，执行查询TodoItem的请求：

请求

-** 响应**

日志输出：

结果返回：

以及响应头信息中包含的api-supported-versions：

验证2: 请求中添加查询字符串api-version

启动Api项目，执行查询TodoItem的请求：

请求

响应

日志输出：

结果返回（可以自己尝试修改内部逻辑，这里我懒了没改实现，不过从日志已经能看出请求确实进入了V2版本的Controller）：

以及响应头信息中包含的api-supported-versions

方法2: 通过请求头携带API版本信息

为了实现这一点，需要在ConfigureApiVersioning中增加配置：

ApiServiceExtensions.cs

// 省略其他...
// 指定请求头中携带用于指定API版本信息的字段
options.ApiVersionReader = new HeaderApiVersionReader("api-version");

验证3: 通过请求头携带API版本信息

启动Api项目，执行查询TodoItem的请求：

请求

响应日志输出：

返回结果就不继续贴了，以及响应头信息中包含的api-supported-versions

方法3: 通过URL路径访问对应的版本

除了这种之外的以上几种方法，都不需要修改接口的URI，而这种方式需要修改URI路径。我们在两个Controller上修改URI如下：

[ApiVersion("2.0")]
[Route("/{v:apiVersion}/todo-item")]
[ApiController]
// 省略其他...

验证4: 通过URI路径选择API版本

启动Api项目，执行查询TodoItem的请求：

请求

响应日志输出：

返回结果就不继续贴了，以及响应头信息中包含的api-supported-versions：

一点扩展

有的时候我们需要标记一个版本的请求为deprecated，但是还不想完全删除这个Controller，可以用下面的方式进行标记，这样返回头中会指出这个版本的API已经处于deprecated状态了。

[ApiVersion("2.0", Deprecated = true)]
[Route("/{v:apiVersion}/todo-item")]
[ApiController]
// 省略其他...

或者在ConfigureApiVersioning中使用Convention进行标记：

// 省略其他...
// 使用Convention标记deprecated
options.Conventions.Controller<TodoItemV2Controller>().HasDeprecatedApiVersion(new ApiVersion(2, 0));

我们再请求2.0版本的API时，仍然可以获取数据，但是得到的返回头中信息如下：

对比使用Convention方式标记的返回头

总结

在本文中我们使用多种方式实现了管理API版本的需求，可以根据具体的需要选择一种进行实现。

以上就是.NET 6开发TodoList应用之实现API版本控制的详细内容，更多关于.NET 6实现API版本控制的资料请关注我们其它相关文章！

赞 (0)

相关推荐

  • .NET 6开发TodoList应用之实现DELETE请求与HTTP请求幂等性

    .NET 6开发TodoList应用之实现DELETE请求与HTTP请求幂等性

    目录 需求 目标 原理与思路 实现 验证 总结 需求 先说明一下关于原本想要去更新的PATCH请求的文章,从目前试验的情况来看,如果是按照.NET 6的项目结构(即只使用一个Program.cs完成程序初始化),那微软官方给出的文档目前还没有对应地更新,按照之前的方式进行JsonPatch的配置是不行的,目前已经有人在Github微软的官方文档Repo下提了ISSUE: .NET 6: JsonPatch in ASP.NET Core web API.并且因为PATCH的使用频率并不高,所以我

  • .NET 6开发TodoList应用之实现数据塑形

    .NET 6开发TodoList应用之实现数据塑形

    目录 需求 目标 原理与思路 实现 定义通用接口和泛型类实现 定义扩展方法 添加依赖注入 修改查询请求和Controller接口 验证 总结 需求 在查询的场景中,还有一类需求不是很常见,就是在前端请求中指定返回的字段,所以关于搜索的最后一个主题我们就来演示一下关于数据塑形(Data Shaping). 目标 实现数据塑形搜索请求. 原理与思路 对于数据塑形来说,我们需要定义一些接口和泛型类实现来完成通用的功能,然后修改对应的查询请求,实现具体的功能. 实现 定义通用接口和泛型类实现 IData

  • .NET 6开发TodoList应用之实现查询分页

    .NET 6开发TodoList应用之实现查询分页

    目录 需求 目标 原理与思路 实现 定义分页结果数据结构 添加对于分页结果的Mapping Profile 创建分页查询请求 创建查询Controller 验证 总结 需求 查询中有个非常常见的需求就是后端分页,实现的方式也不算复杂,所以我们本文仅仅演示一个后端查询分页的例子. 目标 实现分页查询返回. 原理与思路 对于分页查询而言,我们需要在请求中获取当前请求的是第几页,每页请求多少项数据.在返回值中需要告诉前端,当前这一页的所有数据项列表,总共的数据项有多少.为此我们可以定义一个包装类型,供

  • .NET 6开发TodoList应用之请求日志组件HttpLogging介绍

    .NET 6开发TodoList应用之请求日志组件HttpLogging介绍

    背景 因为在上篇演示Action Filter的时候可能是因为举的例子不够好,有小伙伴在评论区指出.NET 6新增加的特性可以实现在视图模型绑定之前允许记录Http请求日志的组件:HttpLogging.这个组件我之前试过,而Action Filter与其用来记录日志,更不如说是为Http请求的接收和响应提供了中间可以修改的机会. 本着让更多的人了解新知识的出发点,这次我们临时把这个主题加进来. 什么是HttpLogging? HttpLogging 是 .NET 6 新加入的一个框架内置的中间

  • .NET 6开发TodoList应用之实现接口请求验证

    .NET 6开发TodoList应用之实现接口请求验证

    目录 需求 目标 原理与思路 实现 验证 一点扩展 总结 参考资料 需求 在响应请求处理的过程中,我们经常需要对请求参数的合法性进行校验,如果参数不合法,将不继续进行业务逻辑的处理.我们当然可以将每个接口的参数校验逻辑写到对应的Handle方法中,但是更好的做法是借助MediatR提供的特性,将这部分与实际业务逻辑无关的代码整理到单独的地方进行管理. 为了实现这个需求,我们需要结合FluentValidation和MediatR提供的特性. 目标 将请求的参数校验逻辑从CQRS的Handler中

  • .NET 6开发TodoList应用之实现ActionFilter

    .NET 6开发TodoList应用之实现ActionFilter

    目录 需求 目标 原理与思路 实现 验证 总结 需求 Filter在.NET Web API项目开发中也是很重要的一个概念,它运行在执行MVC响应的Pipeline中执行,允许我们将一些可以在多个Action之间重用的逻辑抽取出来集中管理.虽然我们在上一篇使用.NET 6开发TodoList应用之实现接口请求验证中演示了如何通过使用MediatR提供的IPipelineBehavior接口在CQRS的Handle方法执行前后插入可重用代码,而本文所演示的Filters作用在Controller的

  • .NET 6开发TodoList应用之实现查询排序

    .NET 6开发TodoList应用之实现查询排序

    目录 需求 目标 原理与思路 实现 验证 总结 需求 关于查询的另一个需求是要根据前端请求的排序字段进行对结果相应的排序. 目标 实现根据排序要求返回排序后的结果 原理与思路 要实现根据前端请求的进行相应排序,结合我们之前写好的Specification,可以比较简单地做到. 实现 我们还是用TodoItem请求来举例,再添加一个排序字段到查询请求中: GetTodoItemsWithConditionQuery.cs using AutoMapper; using AutoMapper.Que

  • .NET 6开发TodoList应用之实现API版本控制

    .NET 6开发TodoList应用之实现API版本控制

    目录 需求 目标 原理与思路 实现 添加Nuget Package并配置服务 实现API版本控制 一点扩展 总结 需求 API接口版本管理,对于一些规模稍大的企业应用来说,是经常需要关注的一大需求.尽管我们的示例程序TodoList很简单,但是我们也可以通过这个应用程序,来实践一下如何管理API接口版本. 目标 实现API接口版本管理. 原理与思路 要实现API版本管理,我们需要这个库:Microsoft.AspNetCore.Mvc.Versioning.它提供了.NET Web项目接口的版本

  • 使用.NET 6开发TodoList应用之引入数据存储的思路详解

    使用.NET 6开发TodoList应用之引入数据存储的思路详解

    需求 作为后端CRUD程序员(bushi,数据存储是开发后端服务一个非常重要的组件.对我们的TodoList项目来说,自然也需要配置数据存储.目前的需求很简单: 需要能持久化TodoList对象并对其进行操作: 需要能持久化TodoItem对象并对其进行操作: 问题是,我们打算如何存储数据? 存储组件的选择非常多:以MSSQL Server/Postgres/MySql/SQLite等为代表的关系型数据库,以MongoDB/ElasticSearch等为代表的非关系型数据库,除此之外,我们还可以

  • 使用.NET 6开发TodoList应用之领域实体创建原理和思路

    使用.NET 6开发TodoList应用之领域实体创建原理和思路

    需求 上一篇文章中我们完成了数据存储服务的接入,从这一篇开始将正式进入业务逻辑部分的开发. 首先要定义和解决的问题是,根据TodoList项目的需求,我们应该设计怎样的数据实体,如何去进行操作? 长文预警!包含大量代码 目标 在本文中,我们希望达到以下几个目标: 定义领域实体: 通过数据库操作领域实体: 原理和思路 虽然TodoList是一个很简单的应用,业务逻辑并不复杂,至少在这个系列文章中我并不想使其过度复杂.但是我还是打算借此简单地涉及领域驱动开发(DDD)的基础概念. 首先比较明确的是,

  • .NET 6开发TodoList应用实现系列背景

    目录 1.列说明 2.系列导航 2.1 使用.NET 6开发TodoList应用文章索引 2.1.1创建项目 2.1.2.NET 6 WebAPI Program.cs的变更 2.1.3Change 1: Top-level statements 2.1.4Change 2: Implicit using directives 2.1.5Change 3: No Startup class 2.2 关于Pipeline的一些知识点 2.2.1Pipeline Sequence 2.2.2app.

  • .NET 6开发TodoList应用引入数据存储

    .NET 6开发TodoList应用引入数据存储

    目录 一.需求 二.目标 三.原理和思路 四.实现 1. 引入Nuget包并进行配置 2. 添加DBContext对象并进行配置# 3. 配置文件修改 4. 主程序配置 5. 本地运行MSSQL Server容器及数据持久化 五.验证 一.需求 作为后端CRUD程序员(bushi,数据存储是开发后端服务一个非常重要的组件.对我们的TodoList项目来说,自然也需要配置数据存储. 目前的需求很简单: 需要能持久化TodoList对象并对其进行操作: 需要能持久化TodoItem对象并对其进行操作

  • .NET 6开发TodoList应用引入第三方日志库

    .NET 6开发TodoList应用引入第三方日志库

    目录 1.需求 2.目标 3.原理和思路 4.实现 4.1日志配置实现 4.2主程序配置 4.3注入使用 5.验证 1.需求 在我们项目开发的过程中,使用.NET 6自带的日志系统有时是不能满足实际需求的,比如有的时候我们需要将日志输出到第三方平台上,最典型的应用就是在各种云平台上,为了集中管理日志和查询日志,通常会选择对应平台的日志SDK进行集成.使用Serilog提供的多种Sink,可以实现将日志写入不同云平台或者是非云平台的日志存储中去,这是我们这篇文章讲要研究的内容. 2.目标 我们将为

  • .NET 6开发TodoList应用实现结构搭建

    .NET 6开发TodoList应用实现结构搭建

    目录 1.TodoList需求简介 2.开发工具 2.1.NET 6 2.2Visual Studio Code 2.3Hoppscotch 3.Clean Architecture简介 4.搭建解决方案结构 5.运行 往期学习: .NET 6开发TodoList应用实现系列背景 1.TodoList需求简介 首先明确一下我们即将开发的这个TodoList应用都需要完成什么功能,我不会一次性把所有的特性诸如允许用户登陆之类的需求全部写上,只是先列出最基本的功能性需求: 我们可以维护一个TodoL

  • .NET 6开发TodoList应用之使用AutoMapper实现GET请求

    .NET 6开发TodoList应用之使用AutoMapper实现GET请求

    目录 需求 目标 原理与思路 实现 引入AutoMapper 实现GET请求 验证 获取所有TodoList列表 获取单个TodoList详情 填一个POST文章里的坑 总结 需求 需求很简单:实现GET请求获取业务数据.在这个阶段我们经常使用的类库是AutoMapper. 目标 合理组织并使用AutoMapper,完成GET请求. 原理与思路 首先来简单地介绍一下这这个类库. 关于AutoMapper 在业务侧代码和数据库实体打交道的过程中,一个必不可少的部分就是返回的数据类型转换.对于不同的

  • .NET 6开发TodoList应用之实现Repository模式

    目录 需求 目标 原理和思路 实现 通用Repository实现 引入使用 验证 总结 需求 经常写CRUD程序的小伙伴们可能都经历过定义很多Repository接口,分别做对应的实现,依赖注入并使用的场景.有的时候会发现,很多分散的XXXXRepository的逻辑都是基本一致的,于是开始思考是否可以将这些操作抽象出去,当然是可以的,而且被抽象出去的部分是可以不加改变地在今后的任何有此需求的项目中直接引入使用. 那么我们本文的需求就是:如何实现一个可重用的Repository模块. 长文预警,

  • .NET 6开发TodoList应用之使用MediatR实现POST请求

    .NET 6开发TodoList应用之使用MediatR实现POST请求

    目录 需求 目标 原理与思路 CQRS模式 中介者Mediator模式 MediatR 实现 引入MediatR 实现Post请求 验证 创建TodoList验证 创建TodoItem验证 总结 参考资料 需求 需求很简单:如何创建新的TodoList和TodoItem并持久化. 初学者按照教程去实现的话,应该分成以下几步:创建Controller并实现POST方法:实用传入的请求参数new一个数据库实体对象:调用IRepository<T>完成数据库的写入,最多会在中间加一层Service.

随机推荐