构建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();

下面直接演示一下：

我们直接在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>