春节假期用 Rust 写了个超好用的 API 设计工具,可以写接口文档和做接口服务

[arlicle]

这次春节在家时间比较长,就有时间做了自己想做的东西,欢迎大家体验提意见:)

Panda api 是一款接口设计工具，它能够生成文档、提供接口模拟服务(在你没写任何代码之前)、自动测试后端接口，有效提升项目的开发效率和质量。

Panda Api 的说明视频 https://www.bilibili.com/video/av88926940?p=1

Panda Api 的快速简易视频教程 https://www.bilibili.com/video/av88926940?p=2

为什么要用 Panda Api?

提升开发效率 和 开发质量:

Panda Api 能够在开发过程中隔离前后端，让前端随心所欲的掌控接口的请求和返回，而不需要后端开发人员介入。开发环境是影响研发效能最大的一个因素之一，不稳定的上游接口环境会让一个非常简单的需求轻松消耗掉数天的时间。当后端的接口还未开发完成，或者接口忽然因为后端某个开发中的功能突然不能工作时，Panda api 可以快速提供接口。

Panda Api 可以提供一个非常高效的前端开发环境和后端测试环境，什么是一个好的开发环境呢？

1、稳定

好的开发环境应该是稳定可用的，不应该在开发过程中受到其他开发人员影响，服务频繁挂掉或者频繁改变，前后端开发的团队成员就深有体会，两边相互影响，然后又导致相互等待，非常影响开发状态和效率。然而很多团队一直是在以这样低效的方式在推进。

2、快速验证

修改代码能够在尽可能短的时间内得到验证也是一个基本诉求，这也是为什么大部分前端构建都会关注 Hot reload 和更高级的 HMR 。有些场景下一次简单前端的修改就要经过长时间等待等待后端开发完成，例如依赖上游修改接口的返回内容，需要修改后端的程序然后重新部署，需要走一遍完整的发布流程来测试某个修改调整，这种改一行等几十分钟的开发方式对效率的拖累是极其恐怖的。

3、一致性

很多项目，因为参与人员少，觉得不需要写什么文档，直接就讨论后开始开发。开发到后面就会发现，大家的共识是不一致的，进一步引发争论和项目的重新调整，如果中途换人或者半年以后再来维护这个项目，就很容易变成一个可怕的泥潭，所有人都不愿意去碰。原因就是一开始我们就没有形成文档。传统的接口文档确实很费时间，Panda api 把文档即服务做好，写文档变成了一个更高效的开发方式。

开发者对于当前的需求应该是有确切认知的，而不是一直不停的怀疑自己的理解到底对不对，相关接口的字段是什么意思。

Panda Api 是如何解决好这几个问题

Panda Api 的三个核心服务：

1. 提供前后端的开发的接口文档
2. 提供前端开发的接口服务
3. 可以进行后端接口测试

Panda Api 接口文档的工具提供以下功能：

1. 提供一份可以前后端浏览的接口文档
2. 使用 json 或 json5 语法来写文档，操作成本、学习成本非常低
3. 接口文档也可以像代码一样进行版本控制，前后端都有维护的权限。Panda api 依赖 git 等版本管理工具来做
4. 可以在定义好文档后，立即为前端开发提供接口服务，不用等待后端开发完成。为前端支持各类请求:GET, POST, PUT, DELETE, OPTIONS
5. 可以使用这个工具进行前端测试和后端测试
6. 可以像 Mock 一样，自动生成相关测试数据

Todo 还在设计开发的功能

1. 支持多种开发环境切换，例如开发环境、测试环境、正式环境
2. 支持 websocket 方式为前端开发提供测试接口服务；支持用 websocket 方式作为客户端进行后端服务测试
3. 其它等你使用后来告诉我

Panda Api 项目地址:

https://github.com/arlicle/panda-api

[Varobjs]

关注下

[LevineChen]

挺棒的

[ivyliner]

挺好的，可以借鉴 yapi

[arlicle]

@ivyliner 好的,谢谢,我去学习一下

[arlicle]

@Varobjs @LevineChen 谢谢,欢迎用一用,提提意见

[zhuzhibin]

老哥我不会 rust 咋办

[huyujievip]

有意思的东西

[wjidea]

有意思，不错可以看看。

[mwylaoma]

Star 一下

[arlicle]

@zhuzhibin 有已编译好的安装包,直接安装运行就可以了

[oneisall8955]

看着不错，想问下路径参数，body 是多层 object 有解析嘛

[arlicle]

@oneisall8955 有的, 文字的简易教程里面有写,你可以看看:)

https://www.debugmyself.com/p/2020/1/15/Panda-api%E4%BD%BF%E7%94%A8%E8%AF%B4%E6%98%8E/

```.language-json5

{
name:"文章列表",
method:"GET",
url:"/post/star/list/",
query:{
page:{name:"分页", type:"number"}
},
response:{
total_page: {name:"总页数", type:"number"},
total_count: {name:"总记录数", type:"number"},
current_page: {name:"当前页码", type:"number"},
result:
[{
$name:"文章列表",
$desc:"只包含用户点赞过的文章列表",
id: {name:"用户 id", type:"number"},
title: {name:"文章标题"},
category: {
$name:"文章所属分类",
$desc:"这里为了体现对象，所以就特意把文章分类用一个对象来表示",
id:{name:"分类 id", type:"number"},
name:{name:"分类名称", type:"string"}
},
content: {name:"文章内容"},
created: {name:"文章创建时间", type:"number"}
}]
}
}
```

[rookiebulls]

关注一波

[ZiLong]

上次 rust 中文社区的日报推过,赞,持续关注

[clf]

关于 mock 这块地方，有一些问题。现在返回结果有这么一个需求：

{
"name":"常见的姓名",
"identity_number":"标准身份证号",
"city":"随机中国城市名",
"constellation":"十二星座",
"zodiac":"生肖"
}

是否能生成这样的数据？而不单单是根据类型生成数据。而且因为你写 mock 模块的时候不可能把生成这些数据的函数或者类型全部内置到我想要的你都有，所以还需要能随时拓展。

另外，现在接口设计与 mock 服务这一块是 mock.js 的天下，就像上面说的 yapi，也是前端使用 mock.js 生成 mock 服务器。

我个人建议是直接基于 mock.js 的语法来实现一个 rust 版的后端 mock 工具，这样能复用接口设计时产生的项目资产。当然，也可以自己设计一套，但这样的话，一些后端语言是 rust，已经使用了其它平台做接口设计的项目，想要迁移到你的平台阻力会很大。

我之前也用 Java 去写过 mock 工具，以上是开发下来最后总结的经验。加油！

[arlicle]

@lychs1998 你好,谢谢你的建议, 目前已支持常见中英文姓名, panda api 有 enum 枚举类型, 星座和生肖可以用 enum 枚举来实现, 也支持正则表达式, 身份证号这些可以通过 正则实现:)
相关字段在这里, 后续会逐步增加更多字段,非常谢谢你的建议,我想一下怎么方便用户自己拓展类型

https://www.debugmyself.com/p/2020/1/29/Panda-api%E5%AD%97%E6%AE%B5%E8%AF%B4%E6%98%8E/

[wm5d8b]

我发现，大家说的 API 管理工具，只管理 HTTP JSON。如果是 XML 格式的，或者通讯协议为 gRPC 或其他私有协议的，就没有工具了。

[arlicle]

@wm5d8b 好建议,我先把 xml 支持加上,谢谢