构建Web API服务

返回总目录《一步一步使用ABP框架搭建正式项目系列教程》


构建动态Web API控制器

ABP可以自动地为应用层生成Web API 层。比如说我们之前创建的应用层:

namespace Noah.ChargeStation.Application.CitiesApp
{
    public interface ICityAppService:IApplicationService
    {
        GetCitiesOutput GetCities(GetCityInput input);
        Task<GetCitiesOutput> GetCitiesAsync(GetCityInput input);
        void UpdateCity(CityInput input);
        Task UpdateCityAsync(CityInput input);
        void CreateCity(CreateCityInput input);
        Task CreateCityAsync(CreateCityInput input);
    }
}

我们想要把这些服务作为Web API 控制器暴露给客户端。ABP通过一句代码就可以自动、动态地为该应用层创建Web API 控制器,在Web API层的Api文件夹下找到xxxWebApiModule类的Initialize方法,添加代码:

DynamicApiControllerBuilder.For<ICityAppService>("ChargeStationAPI/City").Build();

你要做的就这么多!这样,在“/api/services/chargeStationAPI/City”的地方就创建了一个API控制器,所有的方法客户端都可以使用。

ICityAppService是我们想要使用Api 控制器包装的应用服务。对于应用服务这不是强制的而是传统推荐的方式。“ChargeStationAPI/CIty”是一个有着任意命名空间的控制器名字。你应该至少定义一级的命名空间,也可以定义更深层次的命名空间,

比如“myCompany/myApplication/myNamespace1/myNamespace2/myServiceName”。“/api/services/”是所有的Web API控制器的前缀 。因而API控制器的地址将会是这个样子的“/api/services/ChargeStationAPI/City”,GetCities方

法的地址就是“/api/services/ChargeStationAPI/City/getCities”。因为在Javascript中的命名惯例是camelCase,所以方法名就自动转成了camelCase命名的格式。

ForAll 方法

在一个应用中,我们可能有许多应用服务,一个一个地构建api控制器也许是一个乏味而难忘的工作。DynamicAPIControllerBuilder提供了一种方法,可以在一次调用中,对所有的应用服务创建web api 控制器。例如:

DynamicApiControllerBuilder
    .ForAll<IApplicationService>(typeof(ChargeStationApplicationModule).Assembly, "ChargeStationAPI")
    .Build();

ForAll方法是一个接收接口的泛型方法。第一个参数是程序集对象,该程序集包含从给定接口派生的类。最后一个参数是服务命名空间的后缀。比如我们在给定程序集中有ICityAppService和IProvinceAppService。对于该配置,服务就是

“/api/services/ChargeStationAPI/CityApp”和“/api/services/ChargeStationAPI/ProvinceApp”。计算服务名的过程是这样的:移除服务接口的Service和AppService后缀以及I前缀。而且,服务名格式被转成了camelCase格式。如果不喜欢

这个转换,那么你可以通过“WithServiceName”方法决定你命名。除此之外,还有一个Where方法来过滤服务。如果你要为所有的应用服务构建, 其次在此基础上再排除一些,那么这很有用。

重写ForAll方法

可以在ForAll方法之后重写配置。例如:

DynamicApiControllerBuilder
    .ForAll<IApplicationService>(typeof(ChargeStationApplicationModule).Assembly, "ChargeStationAPI")
    .Build();//告诉生成器为所有实现了IApplicationService接口的服务方法创建api控制器
DynamicApiControllerBuilder
    .For<ICityAppService>("ChargeStationAPI/City")
    .ForMethod("CreateCity").DontCreateAction()
    .Build();//告诉生成器不要生成"ChargeStationAPI/City"的"CreateCity"方法

Http 动词

所有的方法默认都是以POST方式创建的。因此,为了使用创建的Web Api方法,客户端应该发送post请求。我们通过不同的方式改变这个行为。

WithVerb方法

可以为一个方法使用WithVerb,像下面这样:

DynamicApiControllerBuilder.For<ICityAppService>("ChargeStationAPI/City")
    .ForMethod("getCities").WithVerb(HttpVerb.Get)
    .Build();

下面直接演示一下:

image

我们直接在Url地址栏发送一次get请求,发现有一个Json格式的数据,错误信息很明确,“输入是null”。虽然报错了,至少可以肯定的是已经生成了web api控制器,只是该控制器需要一个输入参数而已。

HTTP特性

我们可以把HttpGet,HttpPost…特性加到服务接口的方法上:

public interface ICityAppService:IApplicationService
{
    [HttpGet]
    GetCitiesOutput GetCities(GetCityInput input);
    [HttpGet]
    Task<GetCitiesOutput> GetCitiesAsync(GetCityInput input);
    [HttpPost]
    void UpdateCity(CityInput input);
    [HttpPost]
    Task UpdateCityAsync(CityInput input);
    [HttpPost]
    void CreateCity(CreateCityInput input);
    [HttpPost]
    Task CreateCityAsync(CreateCityInput input);
}

要使用这些HTTP特性,就必须向应用层项目中添加Microsoft.AspNet.WebApi.Core Nuget包的引用。添加了HTTP特性之后,就不需要使用上面的WithVerb方法了。

命名惯例

不需要为每一个方法声明HTTP动词,可以使用WithConventionalVerbs方法:

DynamicApiControllerBuilder
    .ForAll<IApplicationService>(typeof(ChargeStationApplicationModule).Assembly, "ChargeStationAPI")
    .WithConventionalVerbs()//根据方法名使用惯例HTTP动词,默认对于所有的action使用Post
    .Build();

这种情况,HTTP动词是通过方法名的前缀决定的:

  • Get:方法名以Get开头。
  • Put:方法名以Put或Update开头。
  • Delete:方法名以Delete或Remove开头。
  • Post:方法名以Post或Create开头。
  • 否则,Post是HTTP动词的默认值。

我们可以通过对特定的方法使用WithVerb方法或者HTTP特性来覆盖上述惯例。

动态Javascript代理

在Javascript中,可以经由Ajax使用动态创建的web api控制器。ABP通过为动态的web api控制器创建动态的Javascript代理简化了这个。因此,可以在Javascript中像调用一个function一样来调用一个动态的web api 控制器action:

 

Javascript代理是动态创建的。使用之前应该将下面动态的脚本包括在页面上。

<script src="~/api/AbpServiceProxies/GetAll"></script>

可以注册done,fail,then等回调函数。服务方法内部使用了abp.ajax。如果需要的话,它们处理错误并显示错误信息。

Ajax参数

可以传递一个自定义的ajax参数给代理方法。可以将它们作为第二个参数传递:

 

abp.services.tasksystem.task.createTask({
    assignedPersonId: 3,
    description: 'a new task description...'
},{ //override jQuery's ajax parameters
    async: false,
    timeout: 30000
}).done(function () {
    abp.notify.success('successfully created a task!');
});

  

单独服务脚本

'/api/AbpServiceProxies/GetAll'在一个文件中生成所有的服务代理。使用'/api/AbpServiceProxies/Get?name=serviceName'也可以生成一个单独的服务代理,只需要在页面中包括下面的代码:

<script src="/api/AbpServiceProxies/Get?name=tasksystem/task" type="text/javascript"></script>

Angular支持

ABP可以作为angular服务暴露动态的api控制器。

(function() {
    angular.module('ChargeStationAPI').controller('CityListController', [
        '$scope', 'abp.services.chargeStationAPI.City',
        function($scope, cityService) {
            var vm = this;
            vm.cities = [];
            taskService.getCities({
                ProvinceCode: 1
            }).success(function(result) {
                vm.cities = result.cities;
            });
        }
    ]);
})();

我们可以使用服务的名字(包含命名空间)注射一个服务。然后,可以作为正常的Javascript函数调用它的function。注意,我们注册到了success句柄上(而不是done),因为它就像在angular的$http服务中。ABP使用AngularJs的$http服务。如果

你想要传递$http配置,可以作为服务方法的最后一个参数传递一个配置对象。

要使用自动生成的服务,应该在页面中包含需要的脚本:

<script src="~/Abp/Framework/scripts/libs/angularjs/abp.ng.js"></script>
<script src="~/api/AbpServiceProxies/GetAll?type=angular"></script>
posted @ 2015-11-09 23:54  tkbSimplest  阅读(...)  评论(...编辑  收藏