Web API系列(三)统一异常处理

  前面讲了webapi的安全验证和参数安全,不清楚的朋友,可以看看前面的文章,《Web API系列(二)接口安全和参数校验》,本文主要介绍Web API异常结果的处理。作为内部或者是对外提供的统一webapi 接口,统一的异常处理,把正确的信息返回给调用者很重要。这样可以让接口开发人员,了解具体的原因所在,这样可以得到有效的错误处理。

  需要注意的是,webapi异常的状态码,尽量不要和业务状态码混淆。可以分为两个不同的字段,或者是状态码的规则不同。相关返回数据的格式,可以参考,前面的文章。

1、常规程序异常处理

  常规的程序异常,指的是webapi 接口程序在执行的时候出现的各种异常情况,可以使用异常筛选器捕获所有异常。

  1. API自定义错误过滤器属性:ApiExceptionAttribute

    /// 

    /// API自定义错误过滤器属性
    ///

 

    public class ApiExceptionHandlingAttribute : ExceptionFilterAttribute
    {
        /// 

        /// 统一对调用异常信息进行处理,返回自定义的异常信息
        ///

 

        /// HTTP上下文对象
        public override void OnException(HttpActionExecutedContext context)
        {
            //自定义异常的处理
            if (context.Exception is NotImplementedException)
            {
                throw new HttpResponseException(new HttpResponseMessage(HttpStatusCode.NotImplemented) 
                {
                    //封装处理异常信息,返回指定JSON对象
                    Content = new StringContent(JsonHelper.ToJson(new ErrorModel((int)HttpStatusCode.NotImplemented, 0, ex.Message)), Encoding.UTF8, "application/json"),
                    ReasonPhrase = "NotImplementedException"
                });
            }
            else if (context.Exception is TimeoutException)
            {
                throw new HttpResponseException(new HttpResponseMessage(HttpStatusCode.RequestTimeout)
                {
                    //封装处理异常信息,返回指定JSON对象
                    Content = new StringContent(JsonHelper.ToJson(new ErrorModel((int)HttpStatusCode.RequestTimeout, 0, ex.Message)), Encoding.UTF8, "application/json"),
                    ReasonPhrase = "TimeoutException"
                });
            }
            //.....这里可以根据项目需要返回到客户端特定的状态码。如果找不到相应的异常,统一返回服务端错误500
            else
            {
                throw new HttpResponseException(new HttpResponseMessage(HttpStatusCode.InternalServerError)
                {
                    //封装处理异常信息,返回指定JSON对象
                    Content = new StringContent(JsonHelper.ToJson(new ErrorModel((int)HttpStatusCode.InternalServerError, 0, ex.Message)), Encoding.UTF8, "application/json"),
                    ReasonPhrase = "InternalServerErrorException"
                });
            }

            //base.OnException(context);

            //记录关键的异常信息
            //Debug.WriteLine(context.Exception);
        }
    }

 

  2. 定义好了错误过滤器,根据实际情况,在不同级别使用统一的异常处理机制。比如,接口action级别,控制器Controller级别或者是全局。

  我们目前的使用的是全局进行异常过滤。在ApiBase 增加异常过滤。

    [ApiAuth]
    [ApiExceptionHandling]
    public class ApiBase : ApiController

2、地址接口异常处理

  对于常规的异常,我们通过上面的处理方式,就可以很好进行拦截并处理了,如果接口异常是全局性的,如访问地不正确,或者调用的接口就不是有效的地址,这样的话,返回的信息就不会被上面的拦截器进行处理了。

如我们给一个无效的API调用路径,在浏览器中获得下面错误结果。

  由于上面结果就无法被我们的常规异常拦截器所捕获,因此不会输出经过封装好的异常信息。

  所以如果需要拦截,我们需要增加自己的消息代理处理,用来捕获这些特殊的异常信息。

 /// 

    /// API自定义错误消息处理委托类。
    /// 用于处理访问不到对应API地址的情况,对错误进行自定义操作。
    /// 

 


    public class CustomErrorMessageDelegatingHandler : DelegatingHandler
    {
        protected override Task SendAsync(HttpRequestMessage request, CancellationToken cancellationToken)
        {
            return base.SendAsync(request, cancellationToken).ContinueWith((responseToCompleteTask) =>
            {
                HttpResponseMessage response = responseToCompleteTask.Result;
                HttpError error = null;
                if (response.TryGetContentValue(out error))
                {
                    //添加自定义错误处理
                    //error.Message = "Your Customized Error Message";
                }

                if (error != null)
                {
                    //获取抛出自定义异常,有拦截器统一解析
                    throw new HttpResponseException(new HttpResponseMessage(HttpStatusCode.NotFound)
                    {
                        //封装处理异常信息,返回指定JSON对象
                        Content = new StringContent(JsonHelper.ToJson(new ErrorModel(404, 0, error.Message)), Encoding.UTF8, "application/json"),
                        ReasonPhrase = "Exception"
                    });
                }
                else
                {
                    return response;
                }
            });
        }
    }

  同时,在WebApiConfig中,注册上相关处理

 public static class WebApiConfig
    {
        public static void Register(HttpConfiguration config)
        {
    
            ..............

            config.MessageHandlers.Add(new CustomErrorMessageDelegatingHandler());

  有了以上这两种异常处理,我们就可以统一我们的调用规则,并进行异常记录和显示了,非常方便。

3、总结

  首先,以上这两种异常处理,我们就可以统一我们的调用规则,但是对于WebApi里面异常的处理机制,可能还不够深入,但对于一般项目的异常处理基本够用。其他朋友,如果还有什么更好的方案,还望不吝赐教,感谢感谢!

  其次,我们目前使用的异常处理,参考于http://www.cnblogs.com/wuhuacong/p/4843422.html。

 

Web API系列(二)接口安全和参数校验

  以前简单介绍过web api 的设计,但是还是有很多朋友问我,如何合理的设计和实现web api。比如,接口安全,异常处理,统一数据返回等问题。所以有必要系统的总结总结 web api 的设计和实现。由于前面已经介绍过web api 的参数和返回格式的设计,《Web API系列(一)设计经验与总结》这次,就来讲讲接口安全。

 

  由于Web API是基于互联网的应用,因此安全性要远比在本地访问数据库的要严格的多,一般通用的做法,是采用几步来保证接口和数据安全:

  1.首先一个是基于CA证书的HTTPS进行数据传输,防止数据被窃听;

  2.然后是采用参数加密签名方式传递,对传递的参数,增加一个加密签名,在服务器端验证签名内容,防止被篡改;

  3.最后是对一般的接口访问,都需要使用用户身份的token进行校验,只要检查通过才允许访问数据。

 

  Web API接口的访问方式,大概可以分为几类:

  1)使用用户名密码。这种方式比较简单,可以有效识别用户的身份(如包括用户信息、密码、或者相关的接口权限等等)。验证成功后,返回相关的数据。

  2)使用安全签名。这种方式提交的数据,URL连接的签名参数是经过安全一定规则的加密的,服务器收到数据后也经过同样规则的安全加密,确认数据没有被中途篡改后,再进行数据修改处理。因此我们可以为不同客户端,如Web/APP/Winfrom等不同接入方式指定不同的加密秘钥,但是秘钥是双方约定的,并不在网络连接上传输,连接传输的一般是这个接入的AppID,服务器通过这个AppID来进行签名参数的加密对比。目前微信后台的回调处理机制,应该就是这么处理的。

  3)公开的接口调用,不需要传入用户令牌、或者对参数进行加密签名的,这种接口一般较少,只是提供一些很常规的数据显示而已。

   

 

  web api 安全校验

  使用用户名密码的实现方式比较简单,这里就不说明如何实现了。就讲一讲安全签名的实现。由于Web API的调用,都是一种无状态的调用方式,所有的接口请求,都要带安全签名。

  

 

  web api核心安全校验代码片断:

 public class QueryData
    {
        public QueryData()
        {

        }

        public QueryData(IEnumerable<KeyValuePair<string, string>> paramList)
        {
            // TODO: Complete member initialization
            try
            {
                if (paramList == null)
                {
                    throw new Exception("请求参数为空!");
                }

                foreach (var param in paramList)
                {
                    m_values[param.Key] = param.Value; //
                }
            }
            catch (Exception ex)
            {
                throw new Exception(ex.Message);
            }
        }

        //采用排序的Dictionary的好处是方便对数据包进行签名,不用再签名之前再做一次排序
        private SortedDictionary<string, object> m_values = new SortedDictionary<string, object>();

        /**
        * 设置某个字段的值
        * @param key 字段名
         * @param value 字段值
        */
        public void SetValue(string key, object value)
        {
            m_values[key] = value;
        }

        /**
        * 根据字段名获取某个字段的值
        * @param key 字段名
         * @return key对应的字段值
        */
        public object GetValue(string key)
        {
            object o = null;
            m_values.TryGetValue(key, out o);
            return o;
        }

        /**
         * 判断某个字段是否已设置
         * @param key 字段名
         * @return 若字段key已被设置,则返回true,否则返回false
         */
        public bool IsSet(string key)
        {
            object o = null;
            m_values.TryGetValue(key, out o);
            if (null != o)
                return true;
            else
                return false;
        }

        public string ToUrl()
        {
            string buff = "";
            foreach (KeyValuePair<string, object> pair in m_values)
            {
                if (pair.Value == null)
                {
                    throw new Exception("内部含有值为null的字段!");
                }

                if (pair.Key != "sign" && pair.Value.ToString() != "")
                {
                    buff += pair.Key + "=" + pair.Value + "&";
                }
            }
            buff = buff.Trim('&');
            return buff;
        }

        public string MakeSign(string appKey = "test")
        {
            //转url格式
            string str = ToUrl();
            //在string后加入API KEY
            str += "&key=" + appKey;
            //MD5加密
            var md5 = MD5.Create();
            var bs = md5.ComputeHash(Encoding.UTF8.GetBytes(str));
            var sb = new StringBuilder();
            foreach (byte b in bs)
            {
                sb.Append(b.ToString("x2"));
            }
            //所有字符转为大写
            return sb.ToString().ToUpper();
        }
      

        public bool CheckSign()
        {
            //如果没有设置签名,则跳过检测
            if (!IsSet("sign"))
            {
                throw new Exception("签名存在但不合法!");
            }
            //如果设置了签名但是签名为空,则抛异常
            else if (GetValue("sign") == null || GetValue("sign").ToString() == "")
            {
                throw new Exception("签名存在但不合法!");
            }

            //获取接收到的签名
            string return_sign = GetValue("sign").ToString();

            //在本地计算新的签名
            string cal_sign = MakeSign();

            if (cal_sign == return_sign)
            {
                return true;
            }
            return false;
        }
    }

代码供大家参考和学习,正式的项目可以根据自己公司的需要去设计,后续也会开源相关的完整项目源代码。

 

Web API系列(一)设计经验与总结

在移动互联网的时代, Web服务已经成为了异构系统之间的互联与集成的主要手段,各种 Web服务几乎都采用REST风格的Web Api来构建。 通过Http协议的形式来. 以Get/Post方式发送请求, 返回json格式(数据更小巧且自描述能力强)的数据。这里就不在介绍REST API 的好处和不足。这些网上一大堆资料。今天就说说,如何构建优秀的REST API ?

目前,各大互联网公司, 对自身的REST Api设计有各自的标准,他们的Api 的设计也非常成熟。 那么,我们应该如何更好的设计我们的接口, 来提高我们 API 的可用性,易用性,可维护性与可扩展性呢?

一. API 设计方案
1. Http的请求分为URL约定规则、请求参数规则
URL规则: http://{server}/{product}/{version}/{logic}/{method}?{query_string}

server: 为具体的服务域名
product: 为应用工程名
version: 为具体版本号, 便于将来的功能扩展, 可以暂定为 v1, v2
logic: 为具体业务逻辑的初步划分, 比如后端管理方法, app端的请求方法
method: 具体业务的方法

具体的请求参数, 由指定的method方法决定, 全都作为HTTP GET/POST的参数列表。

这里很多人会问为什么把 method 和 version 放到在URI中?

因为这样可以使API 版本化,方便版本控制,同时也便于日后API的分流。当然关于是否将版本信息放入url还是放入请求头里面,曾经有过很激烈的争论,各有各的道理。我个人认为放到 URL 中会好一些。具体的大家还是根据自己的业务场景,综合考量吧。

2. Http的响应规则
HTTP响应码为200, 返回结果为JSON字符串的形式:
如果响应结果正确,则返回结果如下所示:
{
data : { // 请求数据,对象或数组均可
user_id: 123,
user_name: “zwz”,
user_avatar_url: “http://www.abc.com/1.jpg”

},
msg : “done”, // 请求状态描述,调试用
success : 1,
code” : 1001, // 业务自定义状态码
extra : { // 其他扩展的数据,字段、内容不定
type: 1,
desc: “签到成功!”
}
}

如果响应结果失败,则返回如下结果:
{
data : { // 请求数据,对象或数组均可
},
msg : “Internal Server Error”, // 请求状态描述,调试用
success : 0,
code : 5001, // 业务自定义状态码
extra : {
}
}

 

3. Auth 权限验证

API 的权限验证,有很多方案,目前成熟的OAuth 2.0框架等,不过 ,最简单的还是利用 Http Header 来完成这一目标。 将token 通过 Header 传递。来实现权限验证。

4. API 在设计的时候,最好不要将业务错误码与HTTP状态码的绑定,重新定义一套业务错误码,来区分HTTP 的状态码。
状态码的定义也最好有一套规范,类似于HTTP 的状态码,可以按照用户相关、授权相关、各种业务,做简单的分类。
// Code 业务自定义状态码定义示例
// 授权相关
1001: 无权限访问
1002: access_token过期
1003: unique_token无效

// 用户相关
2001: 未登录
2002: 用户信息错误
2003: 用户不存在

// 业务相关
3001: 业务XXX
3002: 业务XXX

// 系统异常
5001:Internal Server Error

二. 其他一些建议:

1. 规范统一的命名
使用驼峰式或者下划线格式都可以,统一规范就行。不过,目前基本都是统一小写加下划线比较好。如:user_id,user_name,user_age等。

2. 语义清晰,遵守常用缩写
字段的名字最好能体现字段的类型,遵守一些常用的缩写,如:user_name, task_desc, date_str 等

3. 空值、空字段的处理
空值、空字段的处理也是比较容易出问题。统一空值用null 。除了布尔类型的,其余的空值统一用null表示,客户端保证每种字段的null可以被正常处理。

4. 各个Action 尽量符合CRUD操作的原则。

5. 给不同类型设置默认空值
除了null,尽量对字段设置“默认值”,如数字就是0,字符串就是空字符串””,数组就是空数组[],对象就是空对象{},这样可以避免客户端处理空值产生的异常。
具体的要根据业务、前后端约定而定。
比如,bool 类型的值,统一成数字0和1 。时间日期类型强制只能传标准GMT/UTC时间戳,然后由各自的客户端根据自己的时区、显示要求做处理后显示。

6. 完整的URL
API里面的数据也会有URL类型的,一般来说如用户的头像、各种图片、音频等资源,都是以URL链接的形式返回的。
返回的URL一定要“完整”,主要指的是不要忘记URL里面的协议部分。应该是http://www.abc.com/1.jpg。

7. REST 安全
可以使用固有的 HTTP 基本验证,你还可以考虑通过支持表单验证,LTPA 验证,Open ID 验证等方式,来满足更多的企业安全要求。

8. 尽量将API部署在专用域名之下。例如:https://api.example.com。

9. API返回的数据格式,应该尽量使用JSON,避免使用XML。

10. 返回正确 HTTP 响应代码,同时重新定义一套业务错误码,来区分HTTP 的状态码。

11. 完善的文档,最好能自动生成在线API文档,这样文档能随时保持最新。
目前有很多自动生成API 文档的攻击,例如:SwaggerUI。