+
+
+
+1. 将配置文件 [`Player.postman_collection.json`](https://raw.githubusercontent.com/pingcap-inc/tidb-example-python/main/django_example/Player.postman_collection.json) 导入 [Postman](https://www.postman.com/)。
+
+2. 导入后 **Collections** > **Player** 如图所示：
+
+ 
+
+3. 发送请求：
+
+ - 增加玩家
+
+ 点击 **Create** 标签，点击 **Send** 按钮，发送 `POST` 形式的 `http://localhost:8000/player/` 请求。返回值为增加的玩家个数，预期为 1。
+
+ 
+
+ - 使用 ID 获取玩家信息
+
+ 点击 **GetByID** 标签，点击 **Send** 按钮，发送 `GET` 形式的 `http://localhost:8000/player/1` 请求。返回值为 ID 为 1 的玩家信息。
+
+ 
+
+ - 使用 Limit 批量获取玩家信息
+
+ 点击 **GetByLimit** 标签，点击 **Send** 按钮，发送 `GET` 形式的 `http://localhost:8000/player/limit/3` 请求。返回值为最多 3 个玩家的信息列表。
+
+ 
+
+ - 分页获取玩家信息
+
+ 点击 **GetByPage** 标签，点击 **Send** 按钮，发送 `GET` 形式的 `http://localhost:8080/player/page?index=0&size=2` 请求。返回值为 index 为 0 的页，每页有 2 个玩家信息列表。此外，还包含了分页信息，如偏移量、总页数、是否排序等。
+
+ 
+
+ - 获取玩家个数
+
+ 点击 **Count** 标签，点击 **Send** 按钮，发送 `GET` 形式的 `http://localhost:8000/player/count` 请求。返回值为玩家个数。
+
+ 
+
+ - 玩家交易
+
+ 点击 **Trade** 标签，点击 **Send** 按钮，发送 `PUT` 形式的 `http://localhost:8000/player/trade` 请求。请求参数为售卖玩家 ID `sellID`、购买玩家 ID `buyID`、购买货物数量 `amount` 以及购买消耗金币数 `price`。返回值为交易是否成功。当出现售卖玩家货物不足、购买玩家金币不足或数据库错误时，交易将不成功。并且由于[数据库事务](/develop/dev-guide-transaction-overview.md)保证，不会有玩家的金币或货物丢失的情况。
+
+ 
+
+
+
+
+
+下面使用 curl 请求服务端。
+
+- 增加玩家
+
+ 使用 `POST` 方法向 `/player` 端点发送请求来增加玩家，例如：
+
+ ```shell
+ curl --location --request POST 'http://localhost:8080/player/' --header 'Content-Type: application/json' --data-raw '[{"coins":100,"goods":20}]'
+ ```
+
+ 这里使用 JSON 作为信息的载荷。表示需要创建一个金币数 `coins` 为 100，货物数 `goods` 为 20 的玩家。返回值为创建的玩家信息：
+
+ ```json
+ 1
+ ```
+
+- 使用 ID 获取玩家信息
+
+ 使用 `GET` 方法向 `/player` 端点发送请求来获取玩家信息。此外，还需要在路径上给出玩家的 ID 参数，即 `/player/{id}`。例如，在请求 ID 为 1 的玩家时：
+
+ ```shell
+ curl --location --request GET 'http://localhost:8080/player/1'
+ ```
+
+ 返回值为 ID 为 1 的玩家的信息：
+
+ ```json
+ {
+ "coins": 200,
+ "goods": 10,
+ "id": 1
+ }
+ ```
+
+- 使用 Limit 批量获取玩家信息
+
+ 使用 `GET` 方法向 `/player/limit` 端点发送请求来获取玩家信息。此外，还需要在路径上给出限制查询的玩家信息的总数，即 `/player/limit/{limit}`。例如，在请求最多 3 个玩家的信息时：
+
+ ```shell
+ curl --location --request GET 'http://localhost:8080/player/limit/3'
+ ```
+
+ 返回值为玩家信息的列表：
+
+ ```json
+ [
+ {
+ "coins": 200,
+ "goods": 10,
+ "id": 1
+ },
+ {
+ "coins": 0,
+ "goods": 30,
+ "id": 2
+ },
+ {
+ "coins": 100,
+ "goods": 20,
+ "id": 3
+ }
+ ]
+ ```
+
+- 分页获取玩家信息
+
+ 使用 `GET` 方法向 `/player/page` 端点发送请求来分页获取玩家信息。额外地需要使用 URL 参数，例如在请求页面序号 `index` 为 0，每页最大请求量 `size` 为 2 时：
+
+ ```shell
+ curl --location --request GET 'http://localhost:8080/player/page?index=0&size=2'
+ ```
+
+ 返回值为 `index` 为 0 的页，每页有 2 个玩家信息列表。此外，还包含了分页信息，如偏移量、总页数、是否排序等。
+
+ ```json
+ {
+ "content": [
+ {
+ "coins": 200,
+ "goods": 10,
+ "id": 1
+ },
+ {
+ "coins": 0,
+ "goods": 30,
+ "id": 2
+ }
+ ],
+ "empty": false,
+ "first": true,
+ "last": false,
+ "number": 0,
+ "numberOfElements": 2,
+ "pageable": {
+ "offset": 0,
+ "pageNumber": 0,
+ "pageSize": 2,
+ "paged": true,
+ "sort": {
+ "empty": true,
+ "sorted": false,
+ "unsorted": true
+ },
+ "unpaged": false
+ },
+ "size": 2,
+ "sort": {
+ "empty": true,
+ "sorted": false,
+ "unsorted": true
+ },
+ "totalElements": 4,
+ "totalPages": 2
+ }
+ ```
+
+- 获取玩家个数
+
+ 使用 `GET` 方法向 `/player/count` 端点发送请求来获取玩家个数：
+
+ ```shell
+ curl --location --request GET 'http://localhost:8080/player/count'
+ ```
+
+ 返回值为玩家个数：
+
+ ```json
+ 4
+ ```
+
+- 玩家交易
+
+ 使用 `PUT` 方法向 `/player/trade` 端点发送请求来发起玩家间的交易，例如：
+
+ ```shell
+ curl --location --request PUT 'http://localhost:8080/player/trade' \
+ --header 'Content-Type: application/x-www-form-urlencoded' \
+ --data-urlencode 'sellID=1' \
+ --data-urlencode 'buyID=2' \
+ --data-urlencode 'amount=10' \
+ --data-urlencode 'price=100'
+ ```
+
+ 这里使用 Form Data 作为信息的载荷。表示售卖玩家 ID `sellID` 为 1、购买玩家 ID `buyID` 为 2、购买货物数量 `amount` 为 10、购买消耗金币数 `price` 为 100。
+
+ 返回值为交易是否成功：
+
+ ```
+ true
+ ```
+
+ 当出现售卖玩家货物不足、购买玩家金币不足或数据库错误时，交易将不成功。并且由于[数据库事务](/develop/dev-guide-transaction-overview.md)保证，不会有玩家的金币或货物丢失的情况。
+
+
+
+
+
+为方便测试，你可以使用 [`request.sh`](https://github.com/pingcap-inc/tidb-example-java/blob/main/spring-jpa-hibernate/request.sh) 脚本依次发送以下请求：
+
+1. 循环创建 10 名玩家
+2. 获取 ID 为 1 的玩家信息
+3. 获取至多 3 名玩家信息列表
+4. 获取 `index` 为 0，`size` 为 2 的一页玩家信息
+5. 获取玩家总数
+6. ID 为 1 的玩家作为售出方，ID 为 2 的玩家作为购买方，购买 10 个货物，耗费 100 金币
+
+使用 `make request` 或 `./request.sh` 命令运行此脚本，运行结果如下所示：
+
+```shell
+> make request
+./request.sh
+loop to create 10 players:
+1111111111
+
+get player 1:
+{"id":1,"coins":200,"goods":10}
+
+get players by limit 3:
+[{"id":1,"coins":200,"goods":10},{"id":2,"coins":0,"goods":30},{"id":3,"coins":100,"goods":20}]
+
+get first players:
+{"content":[{"id":1,"coins":200,"goods":10},{"id":2,"coins":0,"goods":30}],"pageable":{"sort":{"empty":true,"unsorted":true,"sorted":false},"offset":0,"pageNumber":0,"pageSize":2,"paged":true,"unpaged":false},"last":false,"totalPages":7,"totalElements":14,"first":true,"size":2,"number":0,"sort":{"empty":true,"unsorted":true,"sorted":false},"numberOfElements":2,"empty":false}
+
+get players count:
+14
+
+trade by two players:
+false
+```
+
+
+
+
+
+## 实现细节
+
+本小节介绍示例应用程序项目中的组件。
+
+### 总览
+
+本示例项目的大致目录树如下所示（删除了有碍理解的部分）：
+
+```
+.
+├── pom.xml
+└── src
+ └── main
+ ├── java
+ │ └── com
+ │ └── pingcap
+ │ ├── App.java
+ │ ├── controller
+ │ │ └── PlayerController.java
+ │ ├── dao
+ │ │ ├── PlayerBean.java
+ │ │ └── PlayerRepository.java
+ │ └── service
+ │ ├── PlayerService.java
+ │ └── impl
+ │ └── PlayerServiceImpl.java
+ └── resources
+ └── application.yml
+```
+
+其中：
+
+- `pom.xml` 内声明了项目的 Maven 配置，如依赖，打包等
+- `application.yml` 内声明了项目的用户配置，如数据库地址、密码、使用的数据库方言等
+- `App.java` 是项目的入口
+- `controller` 是项目对外暴露 HTTP 接口的包
+- `service` 是项目实现接口与逻辑的包
+- `dao` 是项目实现与数据库连接并完成数据持久化的包
+
+### 配置
+
+本节将简要介绍 `pom.xml` 文件中的 Maven 配置，及 `application.yml` 文件中的用户配置。
+
+#### Maven 配置
+
+`pom.xml` 文件为 Maven 配置，在文件内声明了项目的 Maven 依赖，打包方法，打包信息等，你可以通过[创建相同依赖空白程序](#创建相同依赖空白程序可选) 这一节来复刻此配置文件的生成流程，当然，也可直接复制至你的项目来使用。
+
+```xml
+
+