业务接口定义规范

接口定义规范涉及三类定义：

• 内部支持数据类规范：已支持的 Java 原生类和包装类。

• 用户接口类规范：用户定义的 interface，包含 API 调用的 method 声明。

• 用户定义实体类规范：用户定义的实体 class（包含 field 声明），接口类中 method 参数或返回值、其它用户定义实体类将会引用到。

内部支持数据类规范

不支持的数据类型

• 容器类型不能多层嵌套。

• List 或 Map 必须有泛型信息。

• List 或 Map 的泛型信息不能是 array 类型

• 不支持单字节（字节数据 byte [] 是支持的）

• 不支持对象数组，请用 list 代替。

• 属性名不能是 data 和 description，会与 iOS 的属性冲突。

• Map 类型的 key 必须是 String 类型。

• 类型不能是抽象类。

• 类型不能是接口类。

错误的写法：

public class Req {
    private Map<String,List<Person>> map; //容器类型不能多层嵌套。
    private List<Map<Person>> list; //容器类型不能多层嵌套。
    private List list1; //List 或 Map 必须有泛型信息。
    private Map map1; //List 或 Map 必须有泛型信息。
    private List<Person[]> listArray; //List 或 Map 的泛型信息不能是 Array 类型。
    private byte b; //不能为单字节
    private Person[] personArray; //不支持对象数组，请用 List 代替
    private String description; //属性名不能为 description
}

支持的数据类型

boolean, char, double, float, int, long, short
java.lang.Boolean
java.lang.Character
java.lang.Double
java.lang.Float
java.lang.Integer
java.lang.Long
java.lang.Short
java.lang.String
java.util.List，但：必须使用类型参数；不能使用其具体子类 以下简称 List
java.util.Map，但：必须使用类型参数；不能使用其具体子类；key 类型必须是 String 以下简称 Map
Enum
byte[]

正确的写法：

public class Req {
    private String s = "ss";
    private int i;
    private double d;
    private Long l;
    private long l1;
    private boolean b;
    private List<String> stringList;
    private List<Person> personList;
    private Map<String,Person> map;
    private byte[] bytes;
    private EnumType type;
}

public class Person {
    private String name;
    private int age;

用户接口类规范

method 的参数

不可以引用：

• 枚举类型

• 除上文提到的 Map、List、Set 之外的泛型

• 抽象类

• 接口类

• 原生类型的数组

可以引用：

• 具体的实体类，要求引用类型与实际的对象类型保持一致；不可使用父类引用类型指向子类对象。

• 内部支持数据类，但数组、Map、List、Set 这些集合类型不可以嵌套。

如下是错误示例：

Map<String,String[]>
Map<String,List<Person>>(Person为一个具体的实体类)
List<Map<String,Persion>>
List<Persion[]>

method 的返回值

不可以引用：

• 枚举类型

• 除上文提到的 Map、List、Set 之外的泛型

• 抽象类

• 接口类

• 原生类型的数组

可以引用：

• 具体的数据类，要求引用类型与实际的对象类型保持一致；不可使用父类引用类型指向子类对象，例如，不能用 Object 引用指向其它对象。

  注意

  如果父类为具体类，生成工具将检查不出此类错误。

• 内部支持数据类见文章开头定义。数组、Map、List、Set 集合类型不可以嵌套，参见上文相关示例。

method 的定义

• 使用 @OperationType 注解，未加此注解的方法将被生成工具忽略。

• method 不可 overloading。

代码生成工具限制

• 允许接口类定义的继承关系，但会合并层次关系。

• 允许但忽略接口类中定义变量。

• 允许但忽略接口类中的方法声明抛出异常。

• 一个源文件中只能包含一个接口类的定义，不能包含其它类（内部类、匿名类等）的定义。

• 接口类定义本身和其引用到的类型必须为内部支持数据类或可以从源码获得定义。

用户定义实体类规范

field 定义

不可以引用：

• 枚举类型

• 除上文提到的 Map、List、Set 之外的泛型

• 抽象类

• 接口类

• 原生类型的数组

可以引用：

• 具体的实体类，要求引用类型与实际的对象类型保持一致；不可使用父类引用类型指向子类对象。

• 内部支持数据类。数组、Map、List、Set 集合类型不可以嵌套，参见上文相关示例。

• 修饰符包括 transient 的属性将会被忽略。

• final static int 定义的常量（其它不符合该要求定义的常量或静态变量将被忽略）。

  说明

  不推荐 is 开头的成员变量定义。

类的定义

• 可以继承自其它实体类。

• 忽略其方法声明，生成工具将会自动根据实体类字段生成 setter/getter 方法。

代码生成工具限制

• 属性的声明必须一行一个。

• 允许但忽略用户定义实体类实现的接口。

• 一个源文件中只能包含一个用户定义实体类的定义，不能包含其它类（内部类、匿名类等）的定义。

• 接口类定义本身和其引用到的类型必须为内部支持数据类或可以从源码获得定义。