JAX-RS入门 三 ：细节

一、若希望一个Java类能够处理REST请求，则这个类必须至少添加一个@Path("/")的annotation；对于方法，这个annotation是可选的，如果不添加，则继承类的定义。

 

二、一个方法上只有添加了某个Http Method的annotation，例如@GET ，才有资格处理请求。

 

三、@Path 里的值可以是一个复杂的表达式，例如@Path("{id}") ，其中 {id}表达式代码了一个模板参数；一个模板参数是一个定义在@Path里的通配符，它以 { 开始，中间是一堆字母和数字的混合串（不能包含 / 字符），以} 结尾。又如： @Path("{firstName}-{lastName}") .

 

四、@Path也支持正则表达式，例如： @Path("{id: \\d+}") ，其中 \\d+ 表示一个数字。格式为： A : B

 

五、可以自定http method的annotation，具体参考已经有的实现，例如@GET的实现：

@Target({ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
@HttpMethod(HttpMethod.GET)
public @interface GET {
}

其中HttpMethod的实现为：

@Target({ElementType.ANNOTATION_TYPE})
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface HttpMethod {
    
    /**
     * HTTP GET method
     */
    public static final String GET="GET";
    /**
     * HTTP POST method
     */
    public static final String POST="POST"; 
    /**
     * HTTP PUT method
     */
    public static final String PUT="PUT";
    /**
     * HTTP DELETE method
     */
    public static final String DELETE="DELETE";
    /**
     * HTTP HEAD method
     */
    public static final String HEAD="HEAD";
    /**
     * HTTP OPTIONS method
     */
    public static final String OPTIONS="OPTIONS";
    
    /**
     * Specifies the name of a HTTP method. E.g. "GET".
     */
    String value();        
}

因此，可以如下自定义新的http 请求方法：

@Target({ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
@HttpMethod("LOCK")
public @interface LOCK {
}

注：请不要试图重写HttpMethod annotation。

 

六、Path的优先级规则

• 首先检查匹配的字符的个数，匹配的个数越多越优先
• 其次检查内嵌的模板表达式的个数，个数越多越优先
• 最后是非缺省模板表达式的个数；缺省模板即未定义正则表达式的模板

例如以下顺利：

1 /customers/{id}/{name}/address
2 /customers/{id : .+}/address
3 /customers/{id}/address
4 /customers/{id : .+}

如果以上匹配不能解决你的问题，那多半是因为你的设计过于复杂，需要重新审视。

 

七、允许、保留和需要转意的字符

• 所以有 a-z、A-Z、0-9 都被允许
• 所有： _-!.~'()* 都被允许
• 所有： ,;:$&+=?/[]@ 都是保留字符 （需要转意）
• 所有其他字符需要用 % 进行转意；格式为 %HH （%加两个十六进制数）

注：如果Path中uri的表达式包含有需要转意的字符，JAX-RS会自动进行转意；否则会视之为已经进行了URL的encoding。

 

八、Matrix Param

Matrix Param是一个嵌在URI字符串中的name-value对，例如：

http://example.cars.com/mercedes/e55;color=black/2006

 

Matrix Param用于修饰特定的片段，如上修饰e55片段；不同于Query Param，用于修饰整个URI资源。

Matrix Param不出现在@Path的表达式中，例如以上URI对应的@Path的表达式可能是：@Path("/e55/{year}")。

但是可以用@MatrixParam annotation来取得Matrix Param的值，例如：@MatrixParam("color")