本文围绕软件开发中的非功能性质量交付展开讨论，强调了在编码实践中容易被忽视的非功能性需求的重要性。文章指出，非功能性质量（如可维护性、可靠性等）往往因缺乏明确的需求定义和约束机制而难以保证，且其交付水平受个体能力影响较大。为提升非功能性质量，作者以Java语言为例，详细分析了几对相关概念或实践，并提供了具体建议。

写在前面

软件的质量包含功能性、性能、可靠性、可维护性、可移植性等等。工程师产出的代码，首先必须满足功能性（即最基本的业务需求），此外还需要满足其他质量要求。在具体编码实践过程中，功能性的质量交付一般是完整且验证充分的，其他非功能质量的交付结果往往不可控。这是因为：

• 需求并未显式包含非功能质量要求，或因非功能性质量不会直接影响功能性能质量，在分析、设计、交付和验收过程中未考虑这部分质量交付的投入
• 系统的架构原则在交付过程中的约束弱，无法充分识别或保证这类非功能质量需求的交付
• 团队的研发规范和机制未强调或约束对非功能质量的关注和交付
• 个体自发的非功能质量交付行为，最终质量受个体研发能力的影响很大
• 功能性质量可以用有或无来直接界定，而非功能质量大部分情况下（除了性能等可量化的质量）只能用程度指标来度量，因此为交付非功能质量的而做的投入就可以被权衡
• 非功能需求的交付，一般是借助研发平台的能力，遵循一些优秀实践来落实；优秀实践的约束一般比较弱，具体实践时受个体的认知差异影响比较大

本文，以Java语言为基础，整理几对和非功能性质量交付相关的概念或实践。这些概念或实践在实践过程中经常被混用或误用，从而影响了非功能质量的交付水平。通过解释并比较这些概念或实践，来理解这些概念或实践的本质，并给出一些实践建议，来帮助提升非功能性质量的交付水平。事实上，对于互联网平台这样的应用，非功能性质量大部分时候是为研发人员自己交付的。作为工程师应该充分理解这些相似概念，并在具体编码过程中良好的应用。

这些概念和实践包含：

• 注释 VS JavaDoc VS 代码自注释
• 异常信息 VS 异常日志
• 程序异常 VS 业务错误
• 标准化 VS 特例化

注释 VS JavaDoc VS 代码自注释

在Java编程中，注释和Javadoc都是在代码之外，程序员可以添加的文字性描述，用来给代码的维护者或使用者提供代码之外的信息。由于代码本身也是文档，业界产生了一个叫做“代码自注释”的编程实践，通过赋予代码更多的信息来减少代码注释。这三个概念涉及了代码的可维护性。在实际编程过程中，这些代码之外的信息应该以什么方式产出以及应该包含哪些内容，并没有一个绝对的约束，从而导致所产出的注释或Javadoc并没有带来应有的作用。通过正确区分和使用注释、Javadoc和代码自注释，软件工程师可以显著提高代码的可读性和质量，减低代码的维护成本，提高团队的协作效率。

概念比较

• 注释：是程序员在代码中添加的文本，用于解释代码的逻辑或提供开发过程中的思考过程。注释的受众是代码的维护者。
• Javadoc：向其他开发者或使用者提供类、接口、方法和字段的详细说明，用来描述代码所包含的业务语义、提供的业务能力等。Javadoc的受众是代码的维护者和使用者。
• 代码自注释（Self-Documenting Code）：是一种编写代码的实践，旨在通过清晰、简洁的代码结构和命名来传达代码的意图，使代码本身就像文档一样易于理解。这种实践强调代码的可读性，减少对外部注释的依赖，受众是代码维护者。

案例解读

    /**
     * Gets a property from the configuration.
     *
     * @param key property to retrieve
     * @return value as object. Will return user value if exists,
     *        if not then default value if exists, otherwise null
     */
    public Object getProperty(String key) {
        // first, try to get from the 'user value' store
        Object obj = this.get(key);


        if (obj == null) {
            // if there isn't a value there, get it from the
            // defaults if we have them
            if (defaults != null) {
                obj = defaults.get(key);
            }
        }


        return obj;
    }


// org.apache.commons.collections.ExtendedProperties

• 行1-行7：Javadoc描述了该方法的功能、入参和返回值。对于返回值，详细介绍了取值逻辑，便于使用者理解使用该方法的场景
• 行9、行13、行14：方法内的注释解释了如何获取User Value，以及如何获取Default值
• 行15：defaults实际上是一个ExtendedProperties，使用defaults而不是类似extendedProperties这样的变量名，是前者更直接表达了业务语义，这是一种典型的代码自注释风格
• 
  

异常信息 VS 异常日志

在Java编码中，当我们需要处理异常时，一般会对异常信息进行组织，然后将异常信息通过异常继续向上抛出（如果当前无法处理异常），同时打印异常日志。异常信息和异常日志，以不同的方式对外反馈系统发生的异常情况，帮助理解并解决系统问题。它们从产出时机看是一致的，所包含的内容也是高度一致的。在实际编码中，我们会存在“处理了异常但不打印日志”、“异常信息和异常日志输出的比较随意”等情况，这一般是未充分考虑两者在实际的维护中起到的不同作用，从而增加了系统维护的难度和成本。

概念比较

• 异常信息：程序在运行时遇到异常时，抛出的异常所带的描述性信息；它通常包括异常的类型、描述性消息和堆栈跟踪。
• 异常日志：程序在处理异常时，同步输出的日志信息；它通常包含异常发生的原因、异常发生时业务上下文以及其他一些关键信息。

案例解读

public void onApplicationEvent(ApplicationEnvironmentPreparedEvent event) {
    RelaxedPropertyResolver resolver = new RelaxedPropertyResolver(
        event.getEnvironment(), "spring.");
    if (resolver.containsProperty("mandatoryFileEncoding")) {
      String encoding = System.getProperty("file.encoding");
      String desired = resolver.getProperty("mandatoryFileEncoding");
      if (encoding != null && !desired.equalsIgnoreCase(encoding)) {
        logger.error("System property 'file.encoding' is currently '" + encoding
            + "'. It should be '" + desired
            + "' (as defined in 'spring.mandatoryFileEncoding').");
        logger.error("Environment variable LANG is '" + System.getenv("LANG")
            + "'. You could use a locale setting that matches encoding='"
            + desired + "'.");
        logger.error("Environment variable LC_ALL is '" + System.getenv("LC_ALL")
            + "'. You could use a locale setting that matches encoding='"
            + desired + "'.");
        throw new IllegalStateException(
            "The Java Virtual Machine has not been configured to use the "
                + "desired default character encoding (" + desired
                + ").");
      }
    }
  }


// org.springframework.boot.context.FileEncodingApplicationListener

• 行7：触发异常的条件
• 行8-行16：输出异常日志。分3个部分输出，详细说明了异常原因，并给出了完整的修复这个问题的方法，极大方便了系统维护者
• 行17-行20：抛出异常给调用方。异常信息只包含用户定义的编码类型，并没有包含系统的编码，这是考虑了系统编码不应随意暴露给调用者

程序异常 VS 业务错误

一次程序的执行，会得到三种可能得结果：正确、错误和异常。错误是指程序执行得到了用户初始预期不一致的结果，它和正确的结果都属于程序正常执行的范畴；异常是指程序运行时出现了预期外且当前程序无法自行处理的情况，即程序执行不正常。以用户登录场景为例，用户输入了用户名和密码，可能得到三种结果：

• 正确：用户名、密码匹配，用户登录成功
• 错误：即业务错误，用户不存在、密码不正确等原因导致用户本次登录失败。业务错误的情况下，系统可通过提供一些信息指导使用者以正确的方式重试或者通过预先设计的容错机制（如兜底实现）来控制错误带来的业务影响
• 异常：即程序异常，登录服务不可用。此时无法知道用户名以及密码的正确性，也无法指导用户下一步动作

注：本节不讨论是使用异常类型还是错误码来进程序错误的处理，而是为识别程序运行时遇到的一些例外情况是否属于异常提供一种判断方法，以便更好的处理这种例外情况，从而提升系统的可维护性和可用性。当需要处理业务错误或程序异常时，使用特定异常类型或编码，都是具体的手段，不改变这段程序的性质。

概念比较

• 程序异常：由于代码执行过程中的某种意外情况或错误操作导致的执行失败。
• 业务错误：在业务逻辑或功能执行中违背了业务规则或约定，从而导致在表现上非正确的业务结果。再次强调下：这里的业务错误是属于正常的、预期内的业务表现。

案例解读

  public void doFilter(ServletRequest req, ServletResponse res, FilterChain chain)
      throws IOException, ServletException {
    HttpServletRequest request = (HttpServletRequest) req;
    HttpServletResponse response = (HttpServletResponse) res;


    try {
      chain.doFilter(request, response);


      logger.debug("Chain processed normally");
    }
    catch (IOException ex) {
      throw ex;
    }
    catch (Exception ex) {
      // Try to extract a SpringSecurityException from the stacktrace
      Throwable[] causeChain = throwableAnalyzer.determineCauseChain(ex);
      RuntimeException ase = (AuthenticationException) throwableAnalyzer
          .getFirstThrowableOfType(AuthenticationException.class, causeChain);


      if (ase == null) {
        ase = (AccessDeniedException) throwableAnalyzer.getFirstThrowableOfType(
            AccessDeniedException.class, causeChain);
      }


      if (ase != null) {
        handleSpringSecurityException(request, response, chain, ase);
      }
      else {
        // Rethrow ServletExceptions and RuntimeExceptions as-is
        if (ex instanceof ServletException) {
          throw (ServletException) ex;
        }
        else if (ex instanceof RuntimeException) {
          throw (RuntimeException) ex;
        }


        // Wrap other Exceptions. This shouldn't actually happen
        // as we've already covered all the possibilities for doFilter
        throw new RuntimeException(ex);
      }
    }
  }


  private void handleSpringSecurityException(HttpServletRequest request,
      HttpServletResponse response, FilterChain chain, RuntimeException exception)
      throws IOException, ServletException {
    if (exception instanceof AuthenticationException) {
      logger.debug(
          "Authentication exception occurred; redirecting to authentication entry point",
          exception);


      sendStartAuthentication(request, response, chain,
          (AuthenticationException) exception);
    }
    else if (exception instanceof AccessDeniedException) {
      Authentication authentication = SecurityContextHolder.getContext().getAuthentication();
      if (authenticationTrustResolver.isAnonymous(authentication) || authenticationTrustResolver.isRememberMe(authentication)) {
        logger.debug(
            "Access is denied (user is " + (authenticationTrustResolver.isAnonymous(authentication) ? "anonymous" : "not fully authenticated") + "); redirecting to authentication entry point",
            exception);


        sendStartAuthentication(
            request,
            response,
            chain,
            new InsufficientAuthenticationException(
                "Full authentication is required to access this resource"));
      }
      else {
        logger.debug(
            "Access is denied (user is not anonymous); delegating to AccessDeniedHandler",
            exception);


        accessDeniedHandler.handle(request, response,
            (AccessDeniedException) exception);
      }
    }
  }


  protected void sendStartAuthentication(HttpServletRequest request,
      HttpServletResponse response, FilterChain chain,
      AuthenticationException reason) throws ServletException, IOException {
    // SEC-112: Clear the SecurityContextHolder's Authentication, as the
    // existing Authentication is no longer considered valid
    SecurityContextHolder.getContext().setAuthentication(null);
    requestCache.saveRequest(request, response);
    logger.debug("Calling Authentication entry point.");
    authenticationEntryPoint.commence(request, response, reason);
  }


// org.springframework.security.web.access.ExceptionTranslationFilter

• 行11：出现IO异常，无法处理，继续抛出；方法显示声明了调用者需处理IO异常，因此此处没有同步打印日志
• 行17-行27：如果异常链中存在AccessDeniedException或AccessDeniedException异常，则认为是预期内的业务错误，对这种异常进行单独的业务处理（这里实际上是通过异常类型来进行业务逻辑控制）
• 行47-行53：如果异常为AuthenticationException，则进行重定向。此时需同步打印日志，日志级别都为DEBUG

需要再次强调的是，程序异常和程序是否出现Exception没有直接关系，判断程序异常的依据是程序执行过程中遇到的的意外情况是不在预期内且不可解决的。如果程序中设计了一些容错机制来提升健壮性，那么被容错的Exception以及容错的结果都是预期内的，这不属于程序异常范畴，甚至都不算是一种业务错误；但这种情况仍需通过一些审计机制来识别并优化。以推荐场景为例，用户请求推荐服务超时时，系统给出兜底的推荐结果，这个不影响用户基础体验（但影响业务效果）；如果超时的情况是极少数的，那么可以认为这种情况属于正常现象；但如果超时的情况过多，产生较大的业务影响，那就需要进行系统优化。

标准化 VS 特例化

在软件架构和代码设计中，通过构建一个标准层来隔离上层应用与下层应用是实现模块化和低耦合的常见策略，如JDBC隔离了业务层和DB层，从而使得DB的更换对业务层无感。标准化策略有助于提高系统的可维护性、可移植性和灵活性。然而，在实际开发中，有时为了满足特定需求（如性能优化），上层应用可能需要利用下层实现的特性，从而导致对标准接口的使用的偏离。这种情况下，需要充分权衡标准化和特例化的利弊。

实际上，以上提到的标准接口仅仅只是标准化范式的一种，其它的还包含标准规范、优秀实践等。标准化很重要的一个收益就是消除依赖方变化带来的不稳定性；特例化实际上破坏了标准化，使得标准化的收益降低，甚至带来负面影响。

实践比较

• 标准化：所有场景均按照标准范式进行编程，如API使用、风格保持等
• 特例化：根据不同场景进行针对性编程

案例解读

• 案例1：业务应用使用了JDBC来访问数据库，JDBC让应用可以以标准化的方式对接到不同的数据库。业务SQL非必要情况下不要使用和特定数据库绑定的语法（如Oracle数据库特定的SQL语法）。因为后续一旦更换了数据库，而新的数据库不支持此语法，就会产生迁移成本。

• 案例2：在很多Java编程规范中，针对大量字符串的拼接的场景，建议使用StringBuffer等组件来实现而不建议直接使用“+”号。但是因为现在绝大部分Java编译器会针对字符串“+”的写法进行优化，避免产生大量的中间变量，因此大部分时候这并不会带来实质影响。但是这意味着将字符串“+”带来的风险交由特定的编译器来规避，这显示的产生对特定编译器的依赖。如果代码在一个不支持此优化的编译器上编译并上线运行，那么风险就变成问题了。

团队介绍

我们是淘宝集团-供给技术业务架构团队。通过深刻理解业务和技术发展趋势，识别系统在支撑业务过程中的问题，定义面向业务中长期发展的架构命题，并持续推动架构治理和演进，实现架构的不腐化以及灵活高效的响应业务变化。

参考资料

• 《 Javadoc 规范》：https://docs.oracle.com/javase/8/docs/technotes/tools/windows/javadoc.html