网站URL设计规范

前言在设计API的过程，首先我们需要明确的就是 URL 规范。因为如果 URL 不规范，那就会导致让人很烦恼的 URL 路径出现。

设计URL应该遵循的原则 

简单，好记的域名 

简短（short）的URL 

容易录入的URL 

URL能反应站点的结构 

URL是可以被用户猜测和hack的（也鼓励用户如此） 

永久链接，Cool URL don't change

一定要短 

为了URL能被方便的录入，写下，拼写和记忆，URL要尽可能的短. 

 根据w3c提供的参考数据，一个URL的长度最好不要超过80个字节（这并非一个技术限制，经验和统计提供的数据），包括schema和host,port等。 

 大小写策略 

URL的大小写策略要适当，要么全部小写，要么首字母大写，应避免混乱的大小写组合。 

 在Unix世界，文件路径队大小写是敏感的。 

 而在Windows世界，则不对大小写敏感。 

 所以，http://www.ppvv.cn/NEWS 和 http://www.ppvv.cn/news 是两个不同的URI（尽管他们在Windows平台有相同的含义）

URL 映射 

管理员可以重新组织服务器上的文件系统结构，而无需改动URL，这就需要URL和真实的服务器文件系统结构之间有一个映射机制，而不是生硬的对应。

这种映射机制可以通过如下技术手段实现： 

 Aliases，别名，Apache上的目录别名，IIS上的虚拟目录 。

 Symbolic links，符号链接，Unix世界的符号链接 

 Table or database of mappings，数据库映射，URI和文件系统结构的对应关系存储在数据库中 

 标准的重定向

管理员可以简单的通过修改HTTP状态代码来实现服务器文件系统结构变更之后的URL兼容，可以利用的HTTP Status Code有： 

 301 Moved Permanently ([RFC2616] section 10.3.2) 

 302 Found (undefined redirect scheme, [RFC2616] Section 10.3.3) 

 Temporary Redirect ([RFC2616] Section 10.3.8) 

URL 规范 

根据上面的一些准寻的原则，我们可以设定一些项目开发中的 URL 设计规范，如下：

1. 不用大写 （强制）

2. 用中杠-不用下杠_（强制）

3. 参数列表要encode，编码使用utf-8（强制）

4. URI中的名词表示资源集合，使用复数形式。（建议）

5. 增加版本号（建议）

URL增加版本号 

根据项目的更新，原来的URL可能被多个项目所使用，需要兼容原有系统的情况下，支持新业务。 提供给内部系统使用的api，建议使用/api/v1/开头， 提供给前端APP使用的api，建议使用/web-api/v1/开头

/api/v1/loan/web-api/v1/loan

资源集合 vs 单个资源 

URL表示资源的两种方式：资源集合、单个资源。 

资源集合：/zoos //所有动物园/zoos/1/animals //id为1的动物园中的所有动物

单个资源：/zoos/1 //id为1的动物园

避免层级过深的URL 

/ 在url中表达层级，用于按实体关联关系进行对象导航，一般根据id导航。 

 过深的导航容易导致url膨胀，不易维护，如 GET /zoos/1/areas/3/animals/4 

 尽量使用查询参数代替路径中的实体导航，如 GET /animals?zoo=1&area=3