# starrysea-hateoas

**Repository Path**: StarSeaProject/starrysea-hateoas

## Basic Information

- **Project Name**: starrysea-hateoas
- **Description**: 这是星之海项目的HATEOAS引擎包
- **Primary Language**: Java
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2019-02-14
- **Last Updated**: 2020-12-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# starrysea-hateoas

## 简介

HATEOAS，即 Hypermedia As The Engine Of Application State，“超媒体作为应用状态的引擎”的一种设计。有关 HATEOAS 的更多介绍，请参阅[维基百科（英文页面）](https://en.wikipedia.org/wiki/HATEOAS)。<br>
这是 StarrySea 使用 Java 开发的一个 HATEOAS 引擎。<br>

## 添加及部署

### 将该引擎添加到您的项目中

可以使用 Gradle 将其添加到您的项目中。<br>
先在 build.gradle 中添加 JitPack 仓库：
```groovy
allprojects {
    repositories {
        ...
        maven { url 'https://jitpack.io' }
    }
}
```
再添加依赖支持：
```groovy
dependencies {
    implementation 'com.github.StarSeaProject:starrysea-hateoas:1.2.1'
}
```
例子中给出的1.2.1为版本号，我们建议您在引入时先确保当前的最新版本并修改对应的依赖配置。之后重新执行 Gradle Build。

### 在类中导入该引擎

如果您的应用程序使用 WebFlux，添加该语句：
```java
import top.starrysea.hateoas.*;
```
或者使用您的 IDE 的“自动导入”功能。<br>
对于不使用 WebFlux 的应用程序，导入语句为
```java
import top.starrysea.hateoas.functional.*;
```

## 详细使用说明

假设您已经有一个用来存放您想要的数据的类，现在这个教程将帮助您为其添加链接。<br>
接下来将使用[维基百科 HATEOAS 条目](https://en.wikipedia.org/wiki/HATEOAS)上的示例来引导您应该怎么做，这是一个简单的类：
```java
public class Account{
    String username;
    float balance;
}
```

### 创建 resource 类

您需要创建一个继承自 HATEOAS 内 `Resource` 类的新的类。此外，还需要将原来的类的属性添加进这个类里面，并为它们添加get方法，使得这些属性在访问时能被正常显示。例如，您创建了 `MyResource` 类，需要为其添加 `username` 和 `balance` 属性以及 `getUsername` 和 `getBalance` 方法。

### 添加构造方法

添加一个以原来的类作为传入参数的构造方法，将原来的类中的数据放进现在的类中。当然，如果需要的话可以添加更多传入参数。注意这里使用的是 `private`，稍后会指导您创建一个静态方法来调用它。
```java
private MyResource(Account account){
    this.username = account.username;
    this.balance = account.balance;
    /*底下是其他的操作*/
}
```

### 添加链接

您的 Spring 应用程序中会有一个用于区分各种 URL 并根据它们执行不同操作的 `Controller` 类，该类的方法前须有 `@GetMapping`，`@PostMapping` 等注解标明与其绑定的 URL，这对于添加链接至关重要，假设这个类叫 `MyController`。<br>
`Resource` 类中提供了一个 `addLink` 方法来添加链接，该方法接受一个 `Link` 对象，可以使用 `linkTo` 方法来生成一个 `Link` 对象。在构造方法内添加以下语句即可：
```java
this.addLink(linkTo(/*里面是 linkTo 方法的参数，稍后会提到*/));
```

#### 创建一般链接

若您的其中一个方法绑定至一个静态链接，可以使用如下语句来添加：
```java
this.addLink(linkTo(MyController.class, "staticLink"));
```
`linkTo` 方法的第一个参数为您的 `Controller` 类名，第二个参数为该链接对应的方法名。<br>
**注意：** 如果您的方法绑定有多个 URL，则结果内的链接为其绑定的第一个 URL，这可能导致您无法获取到正确的 URL。<br>
得到的 JSON 如下：
```json
{"username":"123456","balance":200.5,"links":[{"href":"/account","method":"GET","template":null,"rel":null}]}
```

#### 创建带参数的链接

您可能会有像 `/account/{username}` 这样的链接，该链接会随 `username` 的值变化。新建一个 `Map<String, String>`，在里面添加如下项： key 值为参数名，在这里是 `"username"`，value 值为参数值，例如 `"12345"`。使用以下语句添加：
```java
this.addLink(linkTo(MyController.class, "dynamicLink", arg));
```
前两个参数的用法和原来相同。 arg 即为刚刚创建的 `Map<String, String>`。<br>
您会看到请求结果内的链接是 `/account/12345`。<br>
整个JSON如下所示，注意href的变化：
```json
{"username":"12345","balance":200.5,"links":[{"href":"/account/12345","method":"GET","template":null,"rel":null}]}
```


#### 创建带附加参数的链接

某些信息不会在URL上体现出来，例如您想为每个链接各添加一段说明文字，显然这是不能通过URL传递的。新建一个 `Map<String, Object>`（这意味着您可以传递更多类型的数据），使用以下语句添加链接，仍然使用上一节的例子：
```java
this.addLink(linkTo(MyController.class, "dynamicLink", arg, template));
```
`template` 是您刚刚创建的 `Map<String, Object>`，在结果中您会看到链接为 `/account/12345`，同时会有一个 `template` 项，里面有您传递的数据。
```json
{"username":"12345","balance":200.5,"links":[{"href":"/account/12345","method":"GET","template":{"desc":"hello","count":100},"rel":null}]}
```

#### 为链接添加关系

链接关系用于描述链接的类型或与当前访问页面的关系。我们定义了一个叫 `RelType` 的枚举来存储这些关系。使用以下语句添加链接：
```java
this.addLink(linkTo(MyController.class, "dynamicLink", arg, template, RelType.PREV));
```
最后的参数即为该枚举中的项。我们只定义了 PREV 与 NEXT ，您可以通过修改该枚举来定义更多的关系。
```json
{"username":"12345","balance":200.5,"links":[{"href":"/account/12345","method":"GET","template":{"desc":"hello","count":100},"rel":"PREV"}]}
```

### 添加获取 resource 类实例的静态方法

该类的构造方法被设为 private ，因此需要通过一个静态方法来获取该 resource 类的实例，这是一个相比使用构造器更加简洁高效的办法。
```java
public static MyResource of(Account account) {
		return new MyResource(account);
	}
```
如果您有多个构造方法，则需要添加多个该方法。<br>
只需调用 `MyResource.of(account)` 即可获取它的一个实例。

## 架构设计

### Link 对象

该对象由 URL ，请求方法（如果使用 `linkTo` 方法添加则默认为 GET ），附加参数和链接关系组成。

### linkTo 方法相关

`linkTo` 方法的实现原理为查找该类内该方法所绑定的 URL ，如果有参数则将参数的值替换上去，得到新的 URL 。这将确保添加的每个链接都是可被响应的。如果该方法绑定了多个 URL ，则会选取第一个去处理，因此需要尽量使每个方法只对应一个 URL ，否则您可能无法得到恰当的链接。<br>
将使用新的 URL ，默认的请求方法和传入的附加参数和链接关系创建新的 `Link` 对象作为返回值。<br>
您也可以直接使用 `addLink` 方法直接添加一个 `Link` 对象。

### 不使用 WebFlux 的解决方案

WebFlux 提供了一整套的服务使得 HATEOAS 引擎变得简洁高效。即使您的应用程序不使用 WebFlux，也仍然可以使用这个引擎。我们在 functional 包内提供了一个类似的使用函数的解决方案，所有相关的类都由我们自己定义，和使用 WebFlux 的版本的使用方法相同。

## 参与贡献

* fork 该项目至您的仓库，将其克隆至您的计算机
* 做出修改并提交
* 在 [JitPack](https://jitpack.io/) 搜索**您账号下的该仓库**，例如 `yourname/Starrysea-hateoas`
* 点击 Commits 选项卡，选取最新提交，并按照提示重新部署
* 运行测试
* 建立 Pull request

## 许可

（待补充）