开放平台之openAPI架构（一）异常处理

1 前言
1.1 背景
    openAPI一套分布式系统，他调用了诸多关联系统并对公司外部提供统一的接口服务。
openAPI的SOA架构图：

    目前各系统的异常规范没有建立，同时也没有特殊的处理，所以openapi无法把具体的异常状态反馈给客户端。只能反馈：“系统内部异常”。这样将导致：

• 增加开放平台与关联系统的沟通成本
• 增加第三方应用与开放平台沟通成本
• 公司形象与品牌受损失
• 后期系统维护困难
• 追踪异常困难

    综上所述，在这样的情况下，我们应当提前“预防火灾”，而不是整天“到处救火”，从根本上提高openAPI的稳定性。

1.2 问题举例
    客户端、最终用户、R&D无法理解服务端的异常。
1.tomcat堆栈信息(http)

2 服务端吞掉了底层异常(ice)
3 格式不一致，http请求返回了不同的数据类型(http)

2 异常概述
2.1 异常分类
按照Java（详细见附录4.1）异常机制分：
    1 检查异常，即需要在接口中声明的异常
该类异常一般在业务层抛出，在展现层处理，如Struts2的Action、SpringMVC的Controller、Ice服务实现类；
    2 非检查异常，也即Runtime异常
该类异常一般在进程或线程的入口处统一处理，如Struts2的异常拦截器。该类异常不需要告诉最终用户异常具体原因，但是要告诉开发人员具体原因。

按照异常产生的原因，大致可分为4种：
    1 用户错误的操作（如输入了错误的数据，违反了业务逻辑等）；
    2 客户端开发人员对服务端接口的错误调用；
    3 服务端开发人员的错误（如bug）；
    4 系统运行环境。
对于第一类异常用检查异常；后面三类用非检查异常。

2.2 异常处理的目的
谁犯了错就清晰明确的告诉犯错者犯了什么错，以便改正。

2.3 异常处理的原则
    针对服务端端和客户端分布式系统的远程接口，客户端需要转译异常并根据api文档定义处理。
    1运行时异常，客户端报警；
    2检查异常，根据不同策略呈现给用户；

2.4 异常编程方案
    在接口中，检查异常与非检查异常的比例中，检查异常越大，说明系统的异常处理机制越健全。
    下图描述了api的类型：

    针对不同的接口类型，我们给出了几种不同的异常声明及处理办法。
下图给出了各类型接口的异常的类型：

    当异常发生时，openAPI只能转译已知异常（异常码）和已知页面（URL和头信息），并根据开放策略提供异常提示和报警。对于其他异常，openAPI无法转译，甚至在http接口中，对于未定义格式的数据或者异常，根本无法获悉服务端的处理情况。
2.4.1 Ice/rmi
    此类接口，与客户端开发技术紧密相连(java)。抛出的异常，可以直接通过异常对象来包装。异常分为定义和未定义2种。
下面是各情况处理图：

2.4.2 http
    此类接口的异常比较复杂。客户端在调用负端时，会传递容器异常和应用异常。而有些容器异常，是由于应用异常抛给容器产生的，有些容器异常是有环境因素导致。因此要保证容器异常和应用异常的边界，就需要应用对所有的应用异常捕捉并进行转译，通过格式化形式反馈给客户端。
下面是各情况处理图：


2.5 异常规范处理方案
2.5.1 流程规范
    本流程可以保证接口文档尽可能的完善。

2.5.2 流程优化
    无论哪种流程，都应该通过开放平台的审核。开放平台从开发接口实现转变为开发规范。
    1 关联系统自行开发
    2 委托开放平台开发

3 异常定义
    http请求，客户端在发送请求时，应当根据format(html,xml,json)参数，提供不同的异常响应。
3.1 http
3.1.1 json
    此类异常描述比较明确，只要按照规范包装即可明确的获取异常状态。

3.1.2 xml
    类似json。

3.1.3 html
    由部门统一开发接口异常提示页。不可报出tomcat内部异常。其中异常信息要同时包含在头部中和页面中。该异常页面通过GET请求调用并传递异常参数errorMessage和errorCode。

3.2 Ice/rmi
    自定义异常类，继承自exception。包含errorMesage、errorCode。

4 附录
4.1 java异常体系
    Java语言的异常处理框架，是Java语言健壮性的一个重要体现。 Java把异常当作对象来处理，并定义一个基类java.lang.Throwable作为所有异常的超类。在Java API中已经定义了许多异常类，这些异常类分为两大类，错误Error和异常Exception。Java异常体系结构呈树状，其层次结构图如图 1所示：

    图 1 Java异常体系结构

    Thorwable类所有异常和错误的超类，有两个子类Error和Exception，分别表示错误和异常。其中异常类Exception又分为运行时异常(RuntimeException)和非运行时异常，这两种异常有很大的区别，也称之为不检查异常（Unchecked Exception）和检查异常（Checked Exception）。下面将详细讲述这些异常之间的区别与联系：
1、Error与Exception
    Error是程序无法处理的错误，比如OutOfMemoryError、ThreadDeath等。这些异常发生时，Java虚拟机（JVM）一般会选择线程终止。
    Exception是程序本身可以处理的异常，这种异常分两大类运行时异常和非运行时异常。程序中应当尽可能去处理这些异常。

2、运行时异常和非运行时异常
   运行时异常都是RuntimeException类及其子类异常，如NullPointerException、IndexOutOfBoundsException等，这些异常是不检查异常，程序中可以选择捕获处理，也可以不处理。这些异常一般是由程序逻辑错误引起的，程序应该从逻辑角度尽可能避免这类异常的发生。
    非运行时异常是RuntimeException以外的异常，类型上都属于Exception类及其子类。从程序语法角度讲是必须进行处理的异常，如果不处理，程序就不能编译通过。如IOException、SQLException等以及用户自定义的Exception异常，一般情况下不自定义检查异常。

4.2 一些反例
    你觉得自己是一个Java专家吗？是否肯定自己已经全面掌握了Java的异常处理机制？在下面这段代码中，你能够迅速找出异常处理的六个问题吗？

OutputStreamWriter out = ... 
java.sql.Connection conn = ... 
try { // ⑸ 
 　Statement stat = conn.createStatement(); 
 　ResultSet rs = stat.executeQuery( 
 　　"select uid, name from user"); 
 　while (rs.next()) 
 　{ 
 　　out.println("ID：" + rs.getString("uid") // ⑹ 
 　　　"，姓名：" + rs.getString("name")); 
 　} 
 　conn.close(); // ⑶ 
 　out.close(); 
 } 
 catch(Exception ex) // ⑵ 
 { 
 　ex.printStackTrace(); //⑴，⑷ 
}

    作为一个Java程序员，你至少应该能够找出两个问题。但是，如果你不能找出全部六个问题，请继续阅读本文。
　　本文讨论的不是Java异常处理的一般性原则，因为这些原则已经被大多数人熟知。我们要做的是分析各种可称为“反例”（anti-pattern）的违背优秀编码规范的常见坏习惯，帮助读者熟悉这些典型的反面例子，从而能够在实际工作中敏锐地察觉和避免这些问题。

反例之一：丢弃异常
    这段代码捕获了异常却不作任何处理，可以算得上Java编程中的杀手。从问题出现的频繁程度和祸害程度来看，它也许可以和C/C++程序的一个恶名远播的问题相提并论??不检查缓冲区是否已满。如果你看到了这种丢弃（而不是抛出）异常的情况，可以百分之九十九地肯定代码存在问题（在极少数情况下，这段代码有存在的理由，但最好加上完整的注释，以免引起别人误解）。
    这段代码的错误在于，异常（几乎）总是意味着某些事情不对劲了，或者说至少发生了某些不寻常的事情，我们不应该对程序发出的求救信号保持沉默和无动于衷。调用一下printStackTrace算不上“处理异常”。不错，调用printStackTrace对调试程序有帮助，但程序调试阶段结束之后，printStackTrace就不应再在异常处理模块中担负主要责任了。
    丢弃异常的情形非常普遍。打开JDK的ThreadDeath类的文档，可以看到下面这段说明：“特别地，虽然出现ThreadDeath是一种‘正常的情形’，但ThreadDeath类是Error而不是Exception的子类，因为许多应用会捕获所有的Exception然后丢弃它不再理睬。”这段话的意思是，虽然ThreadDeath代表的是一种普通的问题，但鉴于许多应用会试图捕获所有异常然后不予以适当的处理，所以JDK把ThreadDeath定义成了Error的子类，因为Error类代表的是一般的应用不应该去捕获的严重问题。可见，丢弃异常这一坏习惯是如此常见，它甚至已经影响到了Java本身的设计。
    那么，应该怎样改正呢？主要有四个选择：
    1、处理异常。针对该异常采取一些行动，例如修正问题、提醒某个人或进行其他一些处理，要根据具体的情形确定应该采取的动作。再次说明，调用printStackTrace算不上已经“处理好了异常”。
    2、重新抛出异常。处理异常的代码在分析异常之后，认为自己不能处理它，重新抛出异常也不失为一种选择。
    3、把该异常转换成另一种异常。大多数情况下，这是指把一个低级的异常转换成应用级的异常（其含义更容易被用户了解的异常）。
    4、不要捕获异常。
    结论一：既然捕获了异常，就要对它进行适当的处理。不要捕获异常之后又把它丢弃，不予理睬。

反例之二：不指定具体的异常
    许多时候人们会被这样一种“美妙的”想法吸引：用一个catch语句捕获所有的异常。最常见的情形就是使用catch(Exception ex)语句。但实际上，在绝大多数情况下，这种做法不值得提倡。为什么呢？
    要理解其原因，我们必须回顾一下catch语句的用途。catch语句表示我们预期会出现某种异常，而且希望能够处理该异常。异常类的作用就是告诉Java编译器我们想要处理的是哪一种异常。由于绝大多数异常都直接或间接从java.lang.Exception派生，catch(Exception ex)就相当于说我们想要处理几乎所有的异常。
    再来看看前面的代码例子。我们真正想要捕获的异常是什么呢？最明显的一个是SQLException，这是JDBC操作中常见的异常。另一个可能的异常是IOException，因为它要操作OutputStreamWriter。显然，在同一个catch块中处理这两种截然不同的异常是不合适的。如果用两个catch块分别捕获SQLException和IOException就要好多了。这就是说，catch语句应当尽量指定具体的异常类型，而不应该指定涵盖范围太广的Exception类。
    另一方面，除了这两个特定的异常，还有其他许多异常也可能出现。例如，如果由于某种原因，executeQuery返回了null，该怎么办？答案是让它们继续抛出，即不必捕获也不必处理。实际上，我们不能也不应该去捕获可能出现的所有异常，程序的其他地方还有捕获异常的机会??直至最后由JVM处理。
    结论二：在catch语句中尽可能指定具体的异常类型，必要时使用多个catch。不要试图处理所有可能出现的异常。

反例之三：占用资源不释放
    异常改变了程序正常的执行流程。这个道理虽然简单，却常常被人们忽视。如果程序用到了文件、Socket、JDBC连接之类的资源，即使遇到了异常，也要正确释放占用的资源。为此，Java提供了一个简化这类操作的关键词finally。
    finally是样好东西：不管是否出现了异常，Finally保证在try/catch/finally块结束之前，执行清理任务的代码总是有机会执行。遗憾的是有些人却不习惯使用finally。
    当然，编写finally块应当多加小心，特别是要注意在finally块之内抛出的异常??这是执行清理任务的最后机会，尽量不要再有难以处理的错误。
    结论三：保证所有资源都被正确释放。充分运用finally关键词。

反例之四：不说明异常的详细信息
    仔细观察这段代码：如果循环内部出现了异常，会发生什么事情？我们可以得到足够的信息判断循环内部出错的原因吗？不能。我们只能知道当前正在处理的类发生了某种错误，但却不能获得任何信息判断导致当前错误的原因。
    printStackTrace的堆栈跟踪功能显示出程序运行到当前类的执行流程，但只提供了一些最基本的信息，未能说明实际导致错误的原因，同时也不易解读。
    因此，在出现异常时，最好能够提供一些文字信息，例如当前正在执行的类、方法和其他状态信息，包括以一种更适合阅读的方式整理和组织printStackTrace提供的信息。
    结论四：在异常处理模块中提供适量的错误原因信息，组织错误信息使其易于理解和阅读。

反例之五：过于庞大的try块
    经常可以看到有人把大量的代码放入单个try块，实际上这不是好习惯。这种现象之所以常见，原因就在于有些人图省事，不愿花时间分析一大块代码中哪几行代码会抛出异常、异常的具体类型是什么。把大量的语句装入单个巨大的try块就象是出门旅游时把所有日常用品塞入一个大箱子，虽然东西是带上了，但要找出来可不容易。
    一些新手常常把大量的代码放入单个try块，然后再在catch语句中声明Exception，而不是分离各个可能出现异常的段落并分别捕获其异常。这种做法为分析程序抛出异常的原因带来了困难，因为一大段代码中有太多的地方可能抛出Exception。
    结论五：尽量减小try块的体积。

反例之六：输出数据不完整
    不完整的数据是Java程序的隐形杀手。仔细观察这段代码，考虑一下如果循环的中间抛出了异常，会发生什么事情。循环的执行当然是要被打断的，其次，catch块会执行??就这些，再也没有其他动作了。已经输出的数据怎么办？使用这些数据的人或设备将收到一份不完整的（因而也是错误的）数据，却得不到任何有关这份数据是否完整的提示。对于有些系统来说，数据不完整可能比系统停止运行带来更大的损失。
    较为理想的处置办法是向输出设备写一些信息，声明数据的不完整性；另一种可能有效的办法是，先缓冲要输出的数据，准备好全部数据之后再一次性输出。
    结论六：全面考虑可能出现的异常以及这些异常对执行流程的影响。

改写后的代码
    根据上面的讨论，下面给出改写后的代码。也许有人会说它稍微有点?嗦，但是它有了比较完备的异常处理机制。

OutputStreamWriter out = ... 
java.sql.Connection conn = ... 
try { 
　Statement stat = conn.createStatement(); 
　ResultSet rs = stat.executeQuery( 
　　"select uid, name from user"); 
　while (rs.next()) 
　{ 
　　out.println("ID：" + rs.getString("uid") + "，姓名: " + rs.getString("name")); 
　} 
} 
catch(SQLException sqlex) 
{ 
　out.println("警告：数据不完整"); 
　throw new ApplicationException("读取数据时出现SQL错误", sqlex); 
} 
catch(IOException ioex) 
{ 
　throw new ApplicationException("写入数据时出现IO错误", ioex); 
} 
finally 
{ 
　if (conn != null) { 
　　try { 
　　　conn.close(); 
　　} 
　　catch(SQLException sqlex2) 
　　{ 
　　　System.err(this.getClass().getName() + ".mymethod - 不能关闭数据库连接: " + sqlex2.toString()); 
　　} 
　} 

　if (out != null) { 
　　try { 
　　　out.close(); 
　　} 
　　catch(IOException ioex2) 
　　{ 
　　　System.err(this.getClass().getName() + ".mymethod - 不能关闭输出文件" + ioex2.toString()); 
　　} 
　} 
}

    本文的结论不是放之四海皆准的教条，有时常识和经验才是最好的老师。如果你对自己的做法没有百分之百的信心，务必加上详细、全面的注释。
    另一方面，不要笑话这些错误，不妨问问你自己是否真地彻底摆脱了这些坏习惯。即使最有经验的程序员偶尔也会误入歧途，原因很简单，因为它们确确实实带来了“方便”。所有这些反例都可以看作Java编程世界的恶魔，它们美丽动人，无孔不入，时刻诱惑着你。也许有人会认为这些都属于鸡皮蒜毛的小事，不足挂齿，但请记住：勿以恶小而为之，勿以善小而不为。


作者简介
昵称:澳洲鸟，猫头哥
姓名:朴海林
QQ:85977328
MSN:[e-mail]
猫头哥的博客：http://phl.iteye.com/