ABP版本控制系统

ABP框架集成了ASPNET-API-版本控制功能并适配C#和JavaScript静态代理和自动API控制器.

启用API版本控制

  1. public override void ConfigureServices(ServiceConfigurationContext context)
  2. {
  3.     context.Services.AddAbpApiVersioning(options =>
  4.     {
  5.         // Show neutral/versionless APIs.
  6.         options.UseApiBehavior = false;
  8.         options.ReportApiVersions = true;
  9.         options.AssumeDefaultVersionWhenUnspecified = true;
  10.     });
  12.     Configure<AbpAspNetCoreMvcOptions>(options =>
  13.     {
  14.         options.ChangeControllerModelApiExplorerGroupName = false;
  15.     });
  16. }

C# 和 JavaScript 静态客户端代理

这个功能不兼容URL路径版本控制， 建议你始终使用Query-String版本控制

示例

Application Services:

  1. public interface IBookAppService : IApplicationService
  2. {
  3.     Task<BookDto> GetAsync();
  4. }
  6. public interface IBookV2AppService : IApplicationService
  7. {
  8.     Task<BookDto> GetAsync();
  10.     Task<BookDto> GetAsync(string isbn);
  11. }

HttpApi Controillers:

  1. [Area(BookStoreRemoteServiceConsts.ModuleName)]
  2. [RemoteService(Name = BookStoreRemoteServiceConsts.RemoteServiceName)]
  3. [ApiVersion("1.0", Deprecated = true)]
  4. [ApiController]
  5. [ControllerName("Book")]
  6. [Route("api/BookStore/Book")]
  7. public class BookController : BookStoreController, IBookAppService
  8. {
  9.     private readonly IBookAppService _bookAppService;
  11.     public BookController(IBookAppService bookAppService)
  12.     {
  13.         _bookAppService = bookAppService;
  14.     }
  16.     [HttpGet]
  17.     public async Task<BookDto> GetAsync()
  18.     {
  19.         return await _bookAppService.GetAsync();
  20.     }
  21. }
  23. [Area(BookStoreRemoteServiceConsts.ModuleName)]
  24. [RemoteService(Name = BookStoreRemoteServiceConsts.RemoteServiceName)]
  25. [ApiVersion("2.0")]
  26. [ApiController]
  27. [ControllerName("Book")]
  28. [Route("api/BookStore/Book")]
  29. public class BookV2Controller : BookStoreController, IBookV2AppService
  30. {
  31.     private readonly IBookV2AppService _bookAppService;
  33.     public BookV2Controller(IBookV2AppService bookAppService)
  34.     {
  35.         _bookAppService = bookAppService;
  36.     }
  38.     [HttpGet]
  39.     public async Task<BookDto> GetAsync()
  40.     {
  41.         return await _bookAppService.GetAsync();
  42.     }
  44.     [HttpGet]
  45.     [Route("{isbn}")]
  46.     public async Task<BookDto> GetAsync(string isbn)
  47.     {
  48.         return await _bookAppService.GetAsync(isbn);
  49.     }
  50. }

生成 CS 和 JS 代理:

  1. [Dependency(ReplaceServices = true)]
  2. [ExposeServices(typeof(IBookAppService), typeof(BookClientProxy))]
  3. public partial class BookClientProxy : ClientProxyBase<IBookAppService>, IBookAppService
  4. {
  5.     public virtual async Task<BookDto> GetAsync()
  6.     {
  7.         return await RequestAsync<BookDto>(nameof(GetAsync));
  8.     }
  9. }
  11. [Dependency(ReplaceServices = true)]
  12. [ExposeServices(typeof(IBookV2AppService), typeof(BookV2ClientProxy))]
  13. public partial class BookV2ClientProxy : ClientProxyBase<IBookV2AppService>, IBookV2AppService
  14. {
  15.     public virtual async Task<BookDto> GetAsync()
  16.     {
  17.         return await RequestAsync<BookDto>(nameof(GetAsync));
  18.     }
  20.     public virtual async Task<BookDto> GetAsync(string isbn)
  21.     {
  22.         return await RequestAsync<BookDto>(nameof(GetAsync), new ClientProxyRequestTypeValue
  23.         {
  24.             { typeof(string), isbn }
  25.         });
  26.     }
  27. }
  1. // controller bookStore.books.book
  3. (function(){
  5. abp.utils.createNamespace(window, 'bookStore.books.book');
  7. bookStore.books.book.get = function(api_version, ajaxParams) {
  8.     var api_version = api_version ? api_version : '1.0';
  9.     return abp.ajax($.extend(true, {
  10.     url: abp.appPath + 'api/BookStore/Book' + abp.utils.buildQueryString([{ name: 'api-version', value: api_version }]) + '',
  11.     type: 'GET'
  12.     }, ajaxParams));
  13. };
  15. })();
  17. // controller bookStore.books.bookV2
  19. (function(){
  21. abp.utils.createNamespace(window, 'bookStore.books.bookV2');
  23. bookStore.books.bookV2.get = function(api_version, ajaxParams) {
  24.     var api_version = api_version ? api_version : '2.0';
  25.     return abp.ajax($.extend(true, {
  26.     url: abp.appPath + 'api/BookStore/Book' + abp.utils.buildQueryString([{ name: 'api-version', value: api_version }]) + '',
  27.     type: 'GET'
  28.     }, ajaxParams));
  29. };
  31. bookStore.books.bookV2.getAsyncByIsbn = function(isbn, api_version, ajaxParams) {
  32.     var api_version = api_version ? api_version : '2.0';
  33.     return abp.ajax($.extend(true, {
  34.     url: abp.appPath + 'api/BookStore/Book/' + isbn + '' + abp.utils.buildQueryString([{ name: 'api-version', value: api_version }]) + '',
  35.     type: 'GET'
  36.     }, ajaxParams));
  37. };
  39. })();

手动更改版本

如果应用服务支持多版本, 你可以注入 ICurrentApiVersionInfo 来切换版本.

  1. var currentApiVersionInfo = _abpApplication.ServiceProvider.GetRequiredService<ICurrentApiVersionInfo>();
  2. var bookV4AppService = _abpApplication.ServiceProvider.GetRequiredService<IBookV4AppService>();
  3. using (currentApiVersionInfo.Change(new ApiVersionInfo(ParameterBindingSources.Query, "4.0")))
  4. {
  5.     book = await bookV4AppService.GetAsync();
  6.     logger.LogWarning(book.Title);
  7.     logger.LogWarning(book.ISBN);
  8. }
  10. using (currentApiVersionInfo.Change(new ApiVersionInfo(ParameterBindingSources.Query, "4.1")))
  11. {
  12.     book = await bookV4AppService.GetAsync();
  13.     logger.LogWarning(book.Title);
  14.     logger.LogWarning(book.ISBN);
  15. }

在JS代理中有一个默认版本, 当然你也可以手动更改.

  2. bookStore.books.bookV4.get("4.0") // Manually change the version.
  3. //Title: Mastering ABP Framework V4.0
  5. bookStore.books.bookV4.get() // The latest supported version is used by default.
  6. //Title: Mastering ABP Framework V4.1

自动API控制器

  1. public override void PreConfigureServices(ServiceConfigurationContext context)
  2. {
  3.     PreConfigure<AbpAspNetCoreMvcOptions>(options =>
  4.     {
  5.         //2.0 Version
  6.         options.ConventionalControllers.Create(typeof(BookStoreWebAppModule).Assembly, opts =>
  7.         {
  8.             opts.TypePredicate = t => t.Namespace == typeof(BookStore.Controllers.ConventionalControllers.v2.TodoAppService).Namespace;
  9.             opts.ApiVersions.Add(new ApiVersion(2, 0));
  10.         });
  12.         //1.0 Compatibility version
  13.         options.ConventionalControllers.Create(typeof(BookStoreWebAppModule).Assembly, opts =>
  14.         {
  15.             opts.TypePredicate = t => t.Namespace == typeof(BookStore.Controllers.ConventionalControllers.v1.TodoAppService).Namespace;
  16.             opts.ApiVersions.Add(new ApiVersion(1, 0));
  17.         });
  18.     });
  19. }
  21. public override void ConfigureServices(ServiceConfigurationContext context)
  22. {
  23.     var preActions = context.Services.GetPreConfigureActions<AbpAspNetCoreMvcOptions>();
  24.     Configure<AbpAspNetCoreMvcOptions>(options =>
  25.     {
  26.         preActions.Configure(options);
  27.     });
  29.     context.Services.AddAbpApiVersioning(options =>
  30.     {
  31.         // Show neutral/versionless APIs.
  32.         options.UseApiBehavior = false;
  34.         options.ReportApiVersions = true;
  35.         options.AssumeDefaultVersionWhenUnspecified = true;
  37.         options.ConfigureAbp(preActions.Configure());
  38.     });
  40.     Configure<AbpAspNetCoreMvcOptions>(options =>
  41.     {
  42.         options.ChangeControllerModelApiExplorerGroupName = false;
  43.     });
  44. }

Swagger/VersionedApiExplorer

  2. public override void ConfigureServices(ServiceConfigurationContext context)
  3. {
  4.     context.Services.AddAbpApiVersioning(options =>
  5.     {
  6.         // Show neutral/versionless APIs.
  7.         options.UseApiBehavior = false;
  9.         options.ReportApiVersions = true;
  10.         options.AssumeDefaultVersionWhenUnspecified = true;
  11.     });
  13.     context.Services.AddVersionedApiExplorer(
  14.         options =>
  15.         {
  16.             // add the versioned api explorer, which also adds IApiVersionDescriptionProvider service
  17.             // note: the specified format code will format the version as "'v'major[.minor][-status]"
  18.             options.GroupNameFormat = "'v'VVV";
  20.             // note: this option is only necessary when versioning by url segment. the SubstitutionFormat
  21.             // can also be used to control the format of the API version in route templates
  22.             options.SubstituteApiVersionInUrl = true;
  23.         });
  25.     context.Services.AddTransient<IConfigureOptions<SwaggerGenOptions>, ConfigureSwaggerOptions>();
  27.     context.Services.AddAbpSwaggerGen(
  28.         options =>
  29.         {
  30.             // add a custom operation filter which sets default values
  31.             options.OperationFilter<SwaggerDefaultValues>();
  33.             options.CustomSchemaIds(type => type.FullName);
  34.         });
  36.     Configure<AbpAspNetCoreMvcOptions>(options =>
  37.     {
  38.         options.ChangeControllerModelApiExplorerGroupName = false;
  39.     });
  40. }
  42. public override void OnApplicationInitialization(ApplicationInitializationContext context)
  43. {
  44.     var app = context.GetApplicationBuilder();
  45.     var env = context.GetEnvironment();
  47.     if (env.IsDevelopment())
  48.     {
  49.         app.UseDeveloperExceptionPage();
  50.     }
  51.     else
  52.     {
  53.         app.UseErrorPage();
  54.         app.UseHsts();
  55.     }
  57.     app.UseHttpsRedirection();
  58.     app.UseStaticFiles();
  59.     app.UseRouting();
  60.     app.UseAbpRequestLocalization();
  62.     app.UseSwagger();
  63.     app.UseSwaggerUI(
  64.         options =>
  65.         {
  66.             var provider = app.ApplicationServices.GetRequiredService<IApiVersionDescriptionProvider>();
  67.             // build a swagger endpoint for each discovered API version
  68.             foreach (var description in provider.ApiVersionDescriptions)
  69.             {
  70.                 options.SwaggerEndpoint($"/swagger/{description.GroupName}/swagger.json", description.GroupName.ToUpperInvariant());
  71.             }
  72.         });
  74.     app.UseConfiguredEndpoints();
  75. }

自定义多版本API控制器

ABP框架不会影响你的API, 你可以根据微软文档自由的实现你的API.

参阅: https://github.com/dotnet/aspnet-api-versioning/wiki

示例源码

你可以在这里得到完整的示例源码: https://github.com/abpframework/abp-samples/tree/master/Api-Versioning