# APIExample
**Repository Path**: fengwenyi/APIExample
## Basic Information
- **Project Name**: APIExample
- **Description**: 以API接口开发为例，探索开发的最佳实践
- **Primary Language**: Java
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 0
- **Created**: 2020-05-23
- **Last Updated**: 2022-05-26
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
Api Example
以API接口开发为例，探索开发的最佳实践
## 分支列表
| 分支名称 | 说明 |
| --- | --- |
| api-result-sample | api-result结合Spring Boot使用实例 |
## 默认启用端口
9191
## 功能
- [x] 包结构规划最佳实践
- [x] API接口返回结果封装最佳解决方案
- [x] 使用Swagger实现漂亮、简洁、大方API接口文档
- [x] Swagger添加请求头
- [x] RESTful API规范接口实例（2020.4.12）
- [ ] Swagger添加接口认证
- [ ] MySQL数据库操作实例
- [ ] MongoDB操作实例
- [ ] Redis操作实例
- [ ] Kafka操作实例
- [ ] RabbitMQ操作实例
- [ ] Elasticsearch操作实例
## 项目目录结构
```
APIExample
├── src
│ ├── main
│ │ ├── java
│ │ │ └── com
│ │ │ └── fengwenyi
│ │ │ └── api_example
│ │ │ ├── bean
│ │ │ │ └── PageResultDataBean
│ │ │ ├── config
│ │ │ │ └── Swagger2Config
│ │ │ ├── controller
│ │ │ │ ├── ApiTestResultController
│ │ │ │ └── ApiUserController
│ │ │ ├── data
│ │ │ │ └── UserData
│ │ │ ├── entity
│ │ │ │ └── UserEntity
│ │ │ ├── exceptions
│ │ │ │ └── DataParseException
│ │ │ ├── handler
│ │ │ │ └── GlobalExceptionHandler
│ │ │ ├── util
│ │ │ │ ├── ApiResultUtils
│ │ │ │ ├── PageResultUtils
│ │ │ │ └── ResultUtils
│ │ │ ├── vo
│ │ │ │ └── param
│ │ │ │ ├── UserFilterParamVO
│ │ │ │ └── UserParamVO
│ │ │ └── ApiExampleApplication
│ │ └── resource
│ │ ├── application.yml
│ │ └── banner.txt
│ └── test
│ └── java
│ └── com
│ └── fengwenyi
│ └── api_example
│ └── ApiExampleApplicationTests
└── pom.xml
```
## 包
`controller`
`business`
`service`
## 依赖
`默认错误页面`
```xml
com.github.iutil
app-boot-starter
${app-boot-starter.version}
```
`API接口结果处理解决方案`
```xml
com.github.iutil
api-result
${api-result.version}
```
`常用工具类`
```xml
com.github.iutil
JavaLib
${JavaLib.version}
```
`接口文档：Swagger`
```xml
io.springfox
springfox-swagger2
2.9.2
io.springfox
springfox-swagger-ui
2.9.2
```
## 测试接口示例
控制台打印
```
[2019-06-05 10:17:02.516] api-test -> get
[2019-06-05 10:17:12.900] api-test -> add
[2019-06-05 10:17:24.037] api-test -> update
[2019-06-05 10:17:36.409] api-test -> delete
```
## 包结构
```
controller -> business -> service -> dbBusiness -> dbService
```
## 关于DB
```
dbService 只能由 dbBusiness调用
在 dbService 里处理所有与数据库相关的异常
查询由 find 开头
携带All：查询所有的数据
携带Use：查询没有被逻辑删除，且已经发布的数据
携带Normal：查询没有被逻辑删除的数据
```
## RESTful API
### HTTP动词
对于资源的具体操作类型，由HTTP动词表示。
常用的HTTP动词有下面五个（括号里是对应的SQL命令）。
```
GET（SELECT）：从服务器取出资源（一项或多项）。
POST（CREATE）：在服务器新建一个资源。
PUT（UPDATE）：在服务器更新资源（客户端提供改变后的完整资源）。
PATCH（UPDATE）：在服务器更新资源（客户端提供改变的属性）。
DELETE（DELETE）：从服务器删除资源。
```
还有两个不常用的HTTP动词。
```
HEAD：获取资源的元数据。
OPTIONS：获取信息，关于资源的哪些属性是客户端可以改变的。
```
下面是一些例子。
```
GET /zoos：列出所有动物园
POST /zoos：新建一个动物园
GET /zoos/ID：获取某个指定动物园的信息
PUT /zoos/ID：更新某个指定动物园的信息（提供该动物园的全部信息）
PATCH /zoos/ID：更新某个指定动物园的信息（提供该动物园的部分信息）
DELETE /zoos/ID：删除某个动物园
GET /zoos/ID/animals：列出某个指定动物园的所有动物
DELETE /zoos/ID/animals/ID：删除某个指定动物园的指定动物
```
### 过滤信息（Filtering）
如果记录数量很多，服务器不可能都将它们返回给用户。API应该提供参数，过滤返回结果。
下面是一些常见的参数。
```
?limit=10：指定返回记录的数量
?offset=10：指定返回记录的开始位置。
?page=2&per_page=100：指定第几页，以及每页的记录数。
?sortby=name&order=asc：指定返回结果按照哪个属性排序，以及排序顺序。
?animal_type_id=1：指定筛选条件
```
参数的设计允许存在冗余，即允许API路径和URL参数偶尔有重复。比如，`GET /zoo/ID/animals` 与 `GET /animals?zoo_id=ID` 的含义是相同的。
### 错误处理
如果状态码是4xx，就应该向用户返回出错信息。一般来说，返回的信息中将error作为键名，出错信息作为键值即可。
```
{
error: "Invalid API key"
}
```
### 返回结果
针对不同操作，服务器向用户返回的结果应该符合以下规范。
```
GET /collection：返回资源对象的列表（数组）
GET /collection/resource：返回单个资源对象
POST /collection：返回新生成的资源对象
PUT /collection/resource：返回完整的资源对象
PATCH /collection/resource：返回完整的资源对象
DELETE /collection/resource：返回一个空文档
```
2020.5.11 规划
```
api-example
api-web
api-webfluex
api-swagger
```
## 版本
1.0.0 2021.01.21-