NCV5-日志异常技术红皮书.doc

日志异常技术红皮书NC-UAP 5.0用友NC-UAP2019-11-141第 页目 录第一章前言1第二章API详解21.系统级日志API22.产品级日志API43.平台级日志API5第三章日志规范71.日志API的选择72.日志级别的选择7第四章异常规范81.规则82.前台代码格式83.Impl类84.DAO类8第 10 页第一章 前言日志系统主要解决运行时刻系统的状态跟踪,为潜在的系统维护和分析提供信息收集的手段。本文档主要介绍NCV5日志API的使用。主要日志配置分为两部分，客户端日志（Debug）和服务器端日志（Logger）第二章 API详解日志系统的API较为简单，大部分程序员只要关注这一节的内容即可。日志系统的API根据需求主要分为二大部分，第一个部分为日志API,第二个部分为Debug的API，主要帮助程序的调试。 1. 系统级日志API系统级的日志交互主要的类为Log,通过该类，通过该API日志时日志系统使用的模块不会动态变化，系统级日志使用的API在应用程序编译时刻就已经确定。该日志只有UAP技术代码（基础技术组）的代码使用，其它产品代码不准使用下面是一个普通的日志API使用的例子：package nc.bs.demo.logging;import nc.bs.logging.Log;public class HelloWorld private static final Log log = Log.getInstance(HelloWorld.class);public static void main(String args) log.debug(Hello,World);HelloWorld定义了一个Log对象常量，他的模块名为HelloWorld的类名，即nc.bs.demo.logging.HelloWorld,运行该程序，如果输出设定为XML那么输出为： Hello,World如果输出格式设定为文本(text),那么输出的结构如下：main nc.bs.demo.logging.HelloWorld Pub Anonymous DEBUG - Hello,World 目前我们并没有配置系统的日志格式和日志输出，系统自动为模块继承匿名模块(Anonymous)的所有的属性。匿名模块没有任何配置自动选取标准输出作为文件的输出格式。后面在描述模块概念，以及日志配置有着详细介绍。普通日志的主要的方法描述如下： Log static Log getInstance(String name)根据模块名称或取该模块的日志实例，参数一般以类名作为参数 static Log getInstance(Class clazz) static Log getInstance(Class clazz)根据类信息获取日志的实例 boolean isDebugEnabled();检查当前模块日志调试是否启用 void debug(Object msg, Throwable throwable); 日志调试信息 void debug(Object msg); 日志调试信息 void debug(Object msg, Class caller, String methodName)为了提高效率，日志调试信息 boolean isInfoEnabled();检查当前模块日志提示信息是否启用 void info(Object msg); 日志调试普通信息 void info(Object msg, Class caller, String methodName)为了提高效率，日志调试普通信息 boolean isWarnEnabled();检查当前模块日志警告是否启用 void warn(Object msg, Throwable throwable);日志警告信息 void warn(Object msg, Throwable throwable, Class caller, String methodName)为了提高效率，日志警告信息 void warn(Object msg);日志警告信息 void warn(Object msg, Class caller, String methodName)为了提高效率，日志警告信息 boolean isErrorEnabled();检查当前模块日志错误报告是否启用 void error(Object msg, Throwable throwable);日志错误信息 void error(Object msg, Throwable throwable, Class caller, String methodName)为了提高效率，日志错误信息 void error(Object msg);日志错误信息 void error(Object msg,Class caller, String methodName)为了提高效率，日志错误信息2. 产品级日志API产品级日志是指日志系统所采用的模块在运行时刻随着程序的运行环境不断发生变化的的日志API，产品级日志的API主类为Logger。产品程序：package nc.bs.demo.logging;import nc.bs.logging.Logger;public class GeneralAlrig public static void sayHello() Logger.debug(hello, world); 可以看出该通用算法的日志模块在finance模块中为finace，在Supply模块中运行为Supply模块。由于不同的模块输出位置、输出格式、输出的信息量等都可以配置，这对于针对单一模块的问题追踪具有一定的意义。Logger的主要方法描述如下：l void init();初始化Logger，根据调用堆栈找到模块，如果找不到，日志到匿名模块。应用程序不需要调用该方法，一般只有平台性的系统调用该方法。 l void init(String module);初始化Logger,传入系统目前的模块，传入参数为空，同init无参数 。参数一般以类名作为参数。应用程序不需要调用该方法，一般只有平台性的系统调用该方法。 l void reset();从当前执行环境中把模块信息进行复位。应用程序不需要调用该方法，一般只有平台性的系统调用该方法。 l String getModule();获取当前环境的模块名 boolean isDebugEnabled();检查当前模块日志调试是否启用 void debug(Object msg, Throwable throwable); 日志调试信息 void debug(Object msg); 日志调试信息 void debug(Object msg, Class caller, String methodName)为了提高效率，日志调试信息 boolean isInfoEnabled();检查当前模块日志提示信息是否启用 void info(Object msg); 日志调试普通信息 void info(Object msg, Class caller, String methodName)为了提高效率，日志调试普通信息 boolean isWarnEnabled();检查当前模块日志警告是否启用 void warn(Object msg, Throwable throwable);日志警告信息 void warn(Object msg, Throwable throwable, Class caller, String methodName)为了提高效率，日志警告信息 void warn(Object msg);日志警告信息 void warn(Object msg, Class caller, String methodName)为了提高效率，日志警告信息 boolean isErrorEnabled();检查当前模块日志错误报告是否启用 void error(Object msg, Throwable throwable);日志错误信息 void error(Object msg, Throwable throwable, Class caller, String methodName)为了提高效率，日志错误信息 void error(Object msg);日志错误信息 void error(Object msg,Class caller, String methodName)为了提高效率，日志错误信息配置日志信息，抛出日志的配置异常。这个部分并不是动态日志特有的API，是配置系统模块的一个API入口，用于特殊的需求。3. 平台级日志API平台级日志是指日志系统所采用的模块在运行时刻随着程序的运行环境不断发生变化的的日志API，平台级日志的API主类为Logger。API同以上产品级代码。主要不同之处为了确保产品的调试方便性，通过平台的日志保证代码放在平台配置的日志中。 void init(String module);初始化Logger,传入系统目前的模块，传入参数为空，同init无参数 。参数一般以类名作为参数。应用程序不需要调用该方法，一般只有平台性的系统调用该方法。 void reset();从当前执行环境中把模块信息进行复位。应用程序不需要调用该方法，一般只有平台性的系统调用该方法。平台级日志的使用遵循有init就必须reset的原则，一般代码结构如下：Logger.init(“module”);try . finally Logger.reset()一般情况下产品程序员不需要调用init, reset，中间件在远程调用的开始和其他的平台（如流程平台）在调度业务代码会主动调用init和reset方法。第三章 日志规范1. 日志API的选择日志API的选择决定程序对日志的要求： 在所有业务组的代码中严禁出现System.out.println()代码，除中间件组代码外 如果日志输出不要求在运行时刻发生变化，用Log，它具有更高的效率,中间件组的纯技术代码使用，其它开发不需使用 如果日志输出需要输出到某个发起调用的模块，而不是代码本身所属模块，使用Logger动态日志。如供应链模块的BService调用财务模块的BService，发起端为供应链模块，我们希望在供应链模块能个够跟踪到信息的时候，财务模块的BService采用Logger作为日志API，如果发起方是它自己模块，则输出在自己的模块内，如果未配置模块，则日志在匿名模块内 基础算法的程序（供给所有模块使用），统一采用Logger作为API 后台业务程序和前后台公共程序、全部业务程序采用Logger。 平台类级程序需要进行采用Logger.init/reset设置，放在各自设置的模块中如：（plateform,pa等）平台级日志的使用遵循有init就必须reset的原则。2. 日志级别的选择目前规定日志只有四种日志级别DEBUG、INFO、 WARN、 ERROR,顺序为DEBUGINFO、 WARNERROR,如果日志级别调的较高，低级别的日志就不能输出如，设置位WARN，那么DEBUG与INFO的信息就不能输出。对四个级别的信息输出： DEBUG: 输出普通的调试信息，主要用于开发环境的信息输出 INFO: 输出提示性的信息，如程序运行所花费的时间等 WARN: 输出警告性的信息，如系统设置了一个需要打开的文件，但是系统在打开他的时候有问题，而用了一个缺省的文件，为此系统还是能够正常运行，但却不符合某些期望，采用警告 ERROR: 错误信息输出，表示系统出了错误，影响了系统的功能，如系统抛出了一个NullPointException,系统不能正常运行。统运行时默认输出级别为ERROR第四章 异常规范1. 规则业务异常必须继承BusinessException或BusinessRuntimeException；2. 前台代码格式必须按照下面内容书写： try /业务处理调用服务接口 catch (BusinessException e) Debug.error(e.getMessage(),e); MessageDialog.showErrorDlg(this,null,e.getMessage(); catch (BusinessRuntimeException e) Debug.error(e.getMessage(),e); MessageDialog.showErrorDlg(this,null,e.getMessage(); catch (Exception e) Debug.error(e.getMessage(),e); MessageDialog.showUnknownErrorDlg(this,e); 3. Impl类1) 业务代码中的业务异常无需捕获，其他异常需要捕获后转换成自己的XX BusinessException或XX RuntimeBusinessException；2) 由业务逻辑引发的异常必须为XX BusinessException或XX RuntimeBusinessException；3) 代码格式：要求在方法上只能抛BusinessExceptionpublic String queryTemplateId(TemplateParaVO