JAVA接口规范遵循 java接口规范有哪些

转载

mob6454cc6e1f98 2023-08-07 19:26:43

文章标签 JAVA接口规范遵循开发规范缩进操作符接口调用 文章分类 Java 后端开发

1　接口规范信息

接口应遵循以下命名原则：

a) 接口名称应使用英文或者英文+数字的形式，如获取库存接口命名为getStore；

b) 接口名称应具有实际意义能体现接口功能，采用英文动宾结构，如获取图书信息接口命名为getBookInfo；

c) 接口命名需要区分大小写；

d) 接口名称总长度不得超过40个字符。

1.1　接口名称

中文名称：接口名称

描述：用于标识接口的文字。

格式约定：见4.2接口命名原则部分的规定。

英文标识：Name

是否必选：必选

是否重复：不重

类型：字符型

长度：变长4-40位

例：getStore

1.2　接口类型

中文名称：接口类型

描述：用于定义接口为公有接口或私有接口的代码。

格式约定：G表示公有接口；S表示私有接口。

英文标识：Type

是否必选：必选

是否重复：不重

类型：字符型

长度：定长1位

例：G

1.3　接口功能类型

中文名称：接口功能类型

描述：用于标示接口功能类型的代码。

格式约定：D表示数据查询接口；T表示文件类接口；C表示数据通讯接口。

英文标识：FunctionalType

是否必选：必选

是否重复：不重

类型：字符型

长度：定长1位

例：C

1.4　接口发布类型

中文名称：接口发布类型

描述：用于标示接口发布类型的代码，当代码为O的时候，必须描述接口发布类型描述数据项。

格式约定：W表示Webservice方式，H表示Http方式，S表示Https方式，O表示除了上述发布方式外其它的方式。

英文标识：ReleaseType

是否必选：必选

是否重复：不重

类型：字符型

长度：定长1位

例：W

1.5　接口调用类型

中文名称：接口调用类型

描述：用于标示接口调用方式的代码。

格式约定：S表示同步调用；A表示异步调用。

英文标识：CallType

是否必选：必选

是否重复：不重

类型：字符型

长度：定长1位

例：S

1.6　接口提供方

中文名称：接口提供方

描述：用于说明提供此接口的软件系统名称。

英文标识：Provider

是否必选：必选

是否重复：不重

类型：字符型

长度：变长2-100位

例：复合出版物生产与投送系统

1.7　接口调用方

中文名称：接口调用方

描述：用于说明调用此接口的软件系统名称。

英文标识：User

是否必选：可选

是否重复：可重

类型：字符型

长度：变长2-100位

例：内容资源管理系统

1.8　接口功能描述

中文名称：接口功能描述

描述：用于解释接口所提供的软件功能。

英文标识：Function

是否必选：必选

是否重复：不重

类型：字符型

长度：变长100-2000位

例：第三方平台通过该接口获取图书信息

1.9　参数名称

中文名称：参数名称

描述：约定的参数名称。

英文标识：ParameterName

是否必选：必选

是否重复：不重

类型：字符型

长度：变长2-50位

例：ParamXml

1.10　参数类型

中文名称：参数类型

描述：用于说明参数数据类型的文字。

英文标识：ParameterType

是否必选：必选

是否重复：不重

类型：字符型

长度：变长2-100位

例：字符型

1.11　参数可选说明

中文名称：参数可选说明

描述：用于说明参数是否必选。

格式约定：F表示可选，T表示必选。

英文标识：Optional

是否必选：必选

是否重复：可重

类型：字符型

长度：定长1位

例：T

1.12　参数描述

中文名称：参数描述

描述：用于说明参数在接口中的作用及参数数据结构说明。

格式约定：参数描述中不可包含计算机识别存在问题的特殊字符，包括“<”、“/”等。

英文标识：Description

是否必选：必选

是否重复：可重

类型：字符型

长度：变长10-4000位

例：String

1.13　接口提示信息

中文名称：接口提示信息

描述：用于解释接口调用时反馈的各类提示性信息代表的业务含义。

英文标识：Message

是否必选：可选

是否重复：不重

类型：字符型

长度：变长0-800位

例：“250000”代表操作成功；接口给出“250001”代表会话失效；接口给出“250002”代表参数为空接口给出

1.14　接口输出说明

中文名称：接口输出说明

描述：用于解释接口执行后输出给调用方的信息。

格式约定：接口输出说明中不可包含计算机识别存在问题的特殊字符，包括“<”、“/”等。

英文标识：ReturnDescription

是否必选：必选

是否重复：不重

类型：字符型

长度：变长10-4000位

例：在双方约定的结果目录（默认是在文件交换目录下一个名为Result的文件夹）中，接收结束后生成一个文件夹，文件夹名称为接收时图书资源文件夹的名称，文件夹内生成一个图书商品_出版社简称_第三方平台简称_年月日时分秒再加5位顺序号_Result.xml，xml中记录了接收的结果，结果状态分为成功、失败、部分成功，并给出了结果原因描述

1.15　接口反馈处理描述

中文名称：接口反馈处理描述

描述：用于解释接口执行完毕后，调用方根据获取的接口输出信息，所需进行的逻辑处理。

英文标识：DealReturn

是否必选：可选

是否重复：不重

类型：字符型

长度：变长10-4000位

例：接口返回值为2001时，应调用获取库存的接口；返回值为9001时，应调用第三方鉴权系统接口；返回值为4001时，应调用新书发布接口

2　软件编码规范

一个类对应一个文件，文件名与类名保持一致。

2.1　类和接口命名规则

类和接口命名：

类和接口的名字一般由大写字母开头而其他字母都小写的英文单词组成；

类必须以名词或名词短语命名，体现类的作用；

接口的名字取决于接口的主要功能和用途。如果接口是使对象具有某种特定的功能，则接口的名字建议使用可以描述这种功能的形容词，否则使用名词或者名词短语。

2.2　方法命名规则

方法命名：

方法命名采用大小写混合的形式。以小写字母开头，名字中其他单词的首字母以大写字母开头，所有其它的单词都为小写字母，不要使用下划线分隔单词；

方法的命名应该能描绘出方法的作用和功能，方法的名字建议使用祈使动词或者动词短语；

获取或者设置类的某种属性的方法显式的命名为 getProperty（）或者setProperty（）。其中property是指类的属性的名字；

用于判断类的布尔属性的方法要显式的命名为 isProperty（），property是指类的属性的名字；

用正确的反义词组命名具有互斥意义的变量或相反动作的函数。

2.3　参数与变量命名规则

参数与变量命名：

参数与变量的命名采用大小写混合的形式。以小写字母开头，名字中其他单词或者只取首字母的缩写单词要以大写字母开头，所有其它的单词都为小写字母，不要使用下划线分隔单词；

参数与变量名字应为名词或者名词短语；

对于变量命名，禁止取单个字符（如i、j、k...），但i、j、k作局部循环变量是允许的；

常量和枚举命名。程序中使用的常量和枚举需要由全部大写的多个单词组成的说明型名称，每个单词之间用下划线分隔。

3　程序注释

3.1　基本要求

程序注释的基本要求如下：

注释的原则有助于对程序的阅读理解，注释的内容要清楚、明了，含义准确，防止注释二义性；

一般情况下，源代码有效注释量应在20%以上；

说明性文件（如头文件.java文件等）头部应进行注释，注释应列出：版权说明、版本号、生成日期、作者、内容、功能、与其它文件的关系、修改日志等，头文件的注释中还应有函数功能简要说明；

/************************************************* 
Copyright (C), 2014-2015, 微讯通系统工程
File name: // 文件名 
Author: Version: Date: // 作者、版本及完成日期 
Description: // 用于详细说明此程序文件完成的主要功能，与其他模块 
// 或函数的接口，输出值、取值范围、含义及参数间的控 
// 制、顺序、独立或依赖等关系 
Others: // 其它内容的说明 
Function List: // 主要函数列表，每条记录应包括函数名及功能简要说明 
1. .... 
History: // 修改历史记录列表，每条修改记录应包括修改日期、修改 
// 者及修改内容简述 
1. Date: 
Author: 
Modification: 
2. ... 
*************************************************/ 
源文件头应进行注释，列出：版权说明、版本号、生成日期、作者、模块目的/功能、主要函数及其功能、修改日志等；
 
/************************************************************ 
Copyright (C), 2014-2015, 国家复合出版系统工程
FileName: test.cpp 
Author: Version : Date: 
Description: // 模块描述 
Version: // 版本信息 
Function List: // 主要函数及其功能 
1. ------- 
History: // 历史修改记录 
<author> <time> <version > <desc> 
David 96/10/12 1.0 build this moudle 
***********************************************************/ 
函数头应进行注释，列出：函数的目的/功能、输入参数、输出参数、返回值、调用关系（函数、表）等；
 
/************************************************* 
Function: // 函数名称 
Description: // 函数功能、性能等的描述 
Calls: // 被本函数调用的函数清单 
Called By: // 调用本函数的函数清单 
Table Accessed: // 被访问的表（此项仅对于牵扯到数据库操作的程序） 
Table Updated: // 被修改的表（此项仅对于牵扯到数据库操作的程序） 
Input: // 输入参数说明，包括每个参数的作 
// 用、取值说明及参数间关系。 
Output: // 对输出参数的说明。 
Return: // 函数返回值的说明 
Others: // 其它说明
*************************************************/ 
通过对函数或过程、变量、结构等正确的命名以及合理地组织代码的结构，使代码成为自注释；
数据结构声明(包括数组、结构、类、枚举等)，如果其命名不是充分自注释的，应加以注释。对数据结构的注释应放在其上方相邻位置，不可放在下面；对结构中的每个域的注释放在此域的右方；
对变量的定义和分支语句（条件分支、循环语句等）应编写注释；
全局变量要有较详细的注释，包括对其功能、取值范围、哪些函数或过程存取它以及存取时注意事项等的说明；
注释与所描述内容进行同样的缩进；
修改代码同时更新相应的注释，保证注释与代码的一致性。不再有用的注释要删除。
3.2　版权注释
版权信息应在文件头部。
 
/************************************************************ 
Copyright (C), 2014-2015, 国家复合出版系统工程
3.3　块注释
块注释要求如下：
通常用于提供对文件，方法，数据结构和算法的描述；
被置于每个文件的开始处以及每个方法之前。它们也可以被用于其他地方，比如方法内部；
在功能和方法内部的块注释应该和它们所描述的代码具有一样的缩进格式；
块注释之首应该有一个空行，用于把块注释和代码分割开来。
 
/*
* Here is a block comment.
*/
3.4　单行注释
单行注释要求如下：
短注释可以显示在一行内，并与其后的代码具有一样的缩进层级；
如果一个注释不能在一行内写完，就该采用块注释；
单行注释之前应该有一个空行。
 
if (condition) {
 
    /* Handle the condition. */
    ...
}
3.5　尾端注释
尾端注释要求如下：
极短的注释可与它们所要描述的代码位于同一行，但应有足够的空白来分开代码和注释；
若有多个短注释出现于大段代码中，它们应该具有相同的缩进。
 
if (a == 2) {
    return TRUE;              /* special case */
} else {
    return isPrime(a);        /* works only for odd a */
}
4　格式要求
4.1　代码格式
4.1.1　页宽
页宽应该设置为80字符。源代码超过这个宽度可能导致无法完整显示。
4.1.2　行长度
单行不应超过80个字符，较长的语句要分成多行书写，在低优先级操作符处划分新行，操作符放在新行之首，划分出的新行要进行适当的缩进，使排版整齐，语句可读。
4.1.3　缩进
程序块要采用缩进风格编写，缩进的空格数为4个。
在函数体的开始、类的定义、结构的定义、枚举的定义以及if、for、do、while、switch、case语句中的程序都要采用如上的缩进方式。
4.1.4　空行
相对独立的程序块之间、变量说明之后必须加空行。在下列情况下应使用一个空行：
在版权声明块、包声明块、引用声明块之后；
在类的声明之间；
在方法的声明之间；
在类中声明最后一个属性之后，声明第一个方法之前。
4.1.5　空格
在两个以上的关键字、变量、常量进行对等操作时，它们之间的操作符之前、之后或者前后要加空格；进行非对等操作时，如果是关系密切的立即操作符（如->）后不应加空格。需遵循以下约定：
逗号、分号只在后面加空格；
 
int a, b, c; 
比较操作符, 赋值操作符"="、 "+="，算术操作符"+"、"%"，逻辑操作符"&&"、"&"，位域操作符"<<"、"^"等双目操作符的前后加空格；
 
if (current_time >= MAX_TIME_VALUE) 
a = b + c;
a *= 2;
a = b ^ 2;
"!"、"~"、"++"、"--"、"&"（地址运算符）等单目操作符前后不加空格；
 
*p = 'a';        // 内容操作"*"与内容之间
flag = !isEmpty; // 非操作"!"与内容之间
p = &mem;        // 地址操作"&" 与内容之间
i++;             // "++","--"与内容之间
"->"、"."前后不加空格；
 
p->id = pid;     // "->"指针前后不加空格
if、for、while、switch等与后面的括号间应加空格，使if等关键字更为突出、明显。
 
if (a >= b && c > d)
4.1.6　括号
同一文件中括号的风格应该保持一致。需遵循以下约定：
首括号与关键词同行，尾括号与关键字同列；左括号“(” 应和函数关键词紧贴在一起，除此以外应当使用空格将“(”同前面内容分开；
右括号“)”除后面是“)”或者“.”以外，其他一律用空格隔开它们；
if、for、do、while、case、switch、default等语句独自占一行，且if、for、do、while等语句的执行语句部分无论多少都要加括号{}。
4.2　语句规则
4.2.1　简单语句
简单语句要求如下：
赋值和表达式每行只包含一条语句；
本地变量的声明应在不同的行中；
数组的[]应该紧跟类型名，而不是数组名。在“[”之前不能有空格。
4.2.2　复合语句
复合语句是包含在大括号中的语句序列，形如“{ 语句 }”。需遵循以下约定：
被括其中的语句应该较之复合语句缩进一个层次；
左大括号“{”应位于复合语句起始行的行尾；
右大括号“}”应另起一行并与复合语句首行对齐；
大括号可以被用于所有语句，包括单个语句，只要这些语句是诸如if-else或for控制结构的一部分。
4.2.3　返回语句
一个带返回值的return语句不使用小括号“()”，除非它们以某种方式使返回值更为显见。 
 
return; 
return myDisk.size(); 
return (size ? size : defaultSize); 
4.2.4　逻辑判断语句
if-else语句宜具有如下格式：
 if (condition) {
     statements;
 }
 
 if (condition) {
     statements;
 } else {
     statements;
 }
 
 if (condition) {
     statements;
 } else if (condition) {
     statements;
 } else {
     statements;
 }
4.2.5　循环语句
for语句规范：
for (initialization; condition; update) 
{
    statements;
}
wile语句规范：
while (condition) 
{
    statements;
}
do-while语句规范：
do 
{
    statements;
} while (condition);
4.2.6　异常处理
try语句规范：
try 
{
    statements;
} catch (exception-declaration) 
{
    statements;
}
 
try 
{
    statements;
} finally 
{
    statements;
}
 
try 
{
    statements;
} catch ( exception-declaration) 
{
    statements;
} finally 
{
    statements;
}

本文章为转载内容，我们尊重原作者对文章享有的著作权。如有内容错误或侵权问题，欢迎原作者联系我们进行内容更正或删除文章。