接口规范

一、xml规范

先看看这个XML文件：

1

2

3

4

5

<article>

    <id><![CDATA[12]]></id>

    <date><![CDATA[20110505]]></date>

    <content><![CDATA[这是一个100000字节的html字符串]]></content>

</article>

这个XML文件的问题在于：

1. 把属性id作为“包含”来处理了，这是错误的，因为id是article的属性，而并非article包含叫id的内容，实际上有时候在事件型解析XML时，我们需要首先确定article的id，这就要求id一定是在其他任何子标签之前被解析器获得，所以id必须放在article的属性里，以保证绝对安全。
2. 滥用cdata，虽然cdata可以保护数据，防止诸如这样的内容，然是如date这样的数据不必要放在cdata里。
3. xml中包含了太多的内容（content标签），xml是用来呈现数据的结构，xml不应该包含过长的内容，例如整个html字符串，而应该给出html的地址。

所以，我们在协商XML时，应该遵循语义化原则，明确“属性”与“包含”的不同。

二、URL参数规范

1. 参数语义性：我们不应该使用诸如number这样毫无具体意义的参数名，而要使用例如querytype这样有意义的。参数的值也是如此，例如一个querytype参数的值不应该是1、2、3、4，而是queryold querynew queryall等等。
2. 参数功能单一性：如果一个参数（例如querycount）只可能取到1、2、3、4四个值（表示不同的查询类型），我们不能为了节省参数传递而将5、6、7、8等等值协商为其他作用。原因很多，首先这样做非常混乱，其次你可能将来会扩展querycount的取值。
3. 参数必须初始化原则：如果有一个参数（例如isRecommend，表示是否推荐），我们在做判断时不应该基于这个参数是否定义了，而应该基于它的值，所以我们规定，这样的参数，我们应该传递字符串true为值。

三、路径引用规范

1. 使用相对路径：当我们向应用端发送含有资源引用的数据（如html），并且这些数据要本地化时，（html）要使用相对路径来引用资源，这样避免html中永远引用绝对地址，导致数据无法显示。
2. 根地址分离：客户端应该保存经常请求地址的根地址，例如“http://172.0.0.10/”，而向服务器返回的数据，应该都不包含根地址，而是客户端来进行地址拼接，这样可以避免根地址变化带来的大幅度程序修改。