附: 关于接口描述的文档内容要求

发表于

概述

接口的概念

在应用软件系统中，接口是程序和系统与外界交互的窗口。本文中所阐述的接口，包括：

应用软件系统提供软件功能供外部软件程序调用；
应用软件系统调用外部系统提供的软件功能；
应用软件系统依据应用级别的交互协议与外系统进行功能和数据的交换；
应用软件系统通过公用文件目录或数据库与外部系统交换信息。

此处中所阐述的接口不包括：

应用软件系统内部功能模块之间的接口调用；
应用软件系统提供的人机交互界面。

接口处理策略

xxxxxxxxxxx是一个庞大的由众多应用子系统构成的复杂分布式系统。各应用子系统之间存在众多的软件接口关系。
在xxxxxxxxxxx中，我们采用SOA的体系架构来解决各应用子系统之间、应用子系统与外部系统之间的接口问题。通过基于ESB服务总线技术的应用支撑平台来发布和管理应用软件系统对外提供公用服务。在这里，服务系指精确定义、封装完善、独立于其他服务所处环境和状态的软件功能。接口服务系指以服务的方式提供的接口实现。
通过支撑平台，各业务子系统接口之间的点对点关系，变成了各业务子系统接口与支撑平台的关系，从而简化了系统间的逻辑关系，应用支撑平台是各业务子系统相互连接的中介和纽带。各业务子系统之间在进行服务请求和服务调用时所需的一些附加工作，如通信协议的转换、路由、消息格式转换、安全性保证等，也可以由应用支撑平台来提供支持。此外，应用支撑平台提供适配器方式以支持文件同步、数据库同步、JMS、FTP等,应用支持平台还提供定制适配器功能接入特殊的外部系统。
通过应用支持平台发布公用服务，将有利于接口服务的复用，以及接口服务的维护和管理。

接口文档规范的必要性

xxxxxxxxxxx建设过程中，各应用软件系统的接口定义、实现、发布和管理是处理好接口问题的四个关键环节，他们贯穿在软件生命周期的全过程。为了保证在这些环节对应用软件系统之间的接口问题进行有效的处理，保证接口的良好定义、合理实现、受控发布和方便管理，有必要对相关技术文档提出规范化要求。
涉及接口定义的技术文档主要有业务需求说明书、软件需求规格说明书；涉及接口实现的技术文档主要有软件概要设计说明书、软件详细设计说明书、用户手册；涉及接口服务发布和管理的技术文档包括接口服务发布和管理规范等。

接口定义的文档规范要求

业务需求说明书中的接口描述

在xxxxxxxxxxx中，业务需求说明书由业主方任命的子项目组负责编制。业务需求说明书中有关接口描述的要求：

  • 宜有专门章节阐述子项目拟分包系统与其它子项目系统及外部系统之间的接口关系；
  • 在描述本系统与外部某系统接口关系时，宜：

具体阐明本系统的哪项或哪些业务功能与所述外部系统存在接口关系；
阐明接口的类型，如向外系统提供数据、从外系统获取数据、对外系统提供功能服务、向外系统请求某项功能服务；
对所述接口作必要的文字解释。

软件需求规格说明书中的接口描述

软件需求规格说明书系由承建方在业务需求说明书的基础上，在系统功能、性能、外部限制条件等方面的进一步明确和细化，作为系统设计、实现、测试的依据。是涉及接口定义的重要文档。
软件需求规格说明书中有关接口定义和描述的要求如下：

  • 软件需求规格说明书中有关与外部系统接口定义的范围应涵盖业务需求说明书中有关接口的描述，并补充业务需求书中遗漏的接口内容；
  • 本系统作为接口对外提供的软件功能，应在软件需求规格说明书中明确阐明该功能。包括接口功能编号、名称、性质（功能服务、数据交换、文件交换等）、接口功能的各输入参数及数据类型，返回的结果数据类型等；
  • 如果接口是作为某种信息交互协议（如Z39.50）的服务端提供的功能，要求阐明支持的协议版本以及是否完全支持该协议，如果不完全支持，要明确列举支持或不支持的功能；
  • 如果接口是某种信息交互协议（如Z39.50）的客户端，且外部系统提供的相应协议服务端功能是本系统相关功能实现的必要条件，须将对外部系统的相关接口实现要求列入软件需求规格说明书中的限制条件部分；
  • 如果系统功能涉及到要使用或访问外部系统提供的功能，须将其列入需求规格说明书中限制条件部分。

接口定义的变更

如果在软件需求评审通过后的实施过程中，原定义或描述的接口发生了变化，须通过变更流程修改软件需求规格说明书；或编制需求文档的补充材料，与原需求规格说明书一起，作为测试和验收的依据。

接口实现的文档规范要求

软件设计说明书中的接口服务实现描述

在软件概要设计说明书中，有关接口实现的要求如下：

  • 须覆盖软件需求说明书中所述对外提供接口功能；
  • 确定接口的实现策略。如采用Web
    Service、EJB、通过网络端口连接对外提供服务、文件目录或数据库同步等。
  • 对外提供的接口功能，需要进行形式化描述，如果不能确定在软件概要设计说明书完全进行接口功能的形式化表述，应在该说明书中明示并在详细设计说明书中给出以供编码实现之用。

用户文档中的接口使用描述

在设计说明书中描述的所有对外提供的接口功能，最终都要落实在用户文档中。具体的用户文档名称，取决于项目合同和软件开发计划中对最终交付文件的规定。如用户使用手册、用户参考手册、用户技术手册等。
各应用软件系统通过该系统的用户文档对外正式公布本系统对外的接口服务的功能和调用方式。