如何做一个完美的api接口？

如何做一个api接口？:我们知道API其实就是应用程序编程接口，可以把它理解为是一种通道，用来和不同软件系统间进行通信，本质上它是预先定义的函数:-api，接口

1

我们知道API其实就是应用程序编程接口，可以把它理解为是一种通道，用来和不同软件系统间进行通信，本质上它是预先定义的函数。API有很多种形式，最为常见的就是以HTTP协议来提供服务（如：RESTful），只要符合规范就可正常使用。现在各类企业在信息化这块都会用到第三方提供的API，也会提供API给第三方调用，因此设计API也是需要慎重的。

具体该如何开发设计一个良好的API接口呢？

明确功能

在设计之初就需要将API详细功能整理出来，按业务功能点或模块来划分，明确此API需要提供哪些功能。

代码逻辑清晰

保持代码整洁性，增加必要的注释，接口确保功能单一，如果一个接口需要复杂的业务逻辑，建议拆分成多个接口或者将功能独立封装成公共方法，避免接口里代码过多，不利于后期人员维护和后期迭代。

必要的安全校验机制

目前Web应用很容易遭遇数据窃取、篡改、非法提交、重复请求等安全问题，API的安全校验机制是必不可少的。常用解决方案就是采用数字签名形式，将每个HTTP请求都加上签名，服务器端校验签名合法性来保证请求是否合法。

日志记录

为便于及时定位问题，日志是必不可少的。

降低耦合度

一个良好的API应该是越简单越好，如果API间业务耦合度过高很容易因某块代码异常导致相关API的不可用，尽可能避免API间的复杂调用关系。

返回有意义的状态码

API返回数据中要携带状态码数据，比如200代表请求正常，500代表服务器内部错误等。返回通用的状态码有利于问题定位，比如可参考以下状态码：

开发文档

既然API是提供给第三方或内部使用的，那开发文档是必不可少的，否则他人不知道如何调用。一个良好的API开发文档应包含以下元素：

1、当前API架构模式讲解、开发工具及版本、系统依懒等环境信息；

2、当前API提供哪些功能；

3、API模块间的依懒关系；

4、调用规则、注意事项；

5、部署注意事项等。

---

一个好的API必然是易使用，易看懂，易扩展，难误用，安全性高，功能强大的API。要做到上面几点并不容易，但是我们应当遵从上述原则结合业务本身合理的划分设计API。

以上就是我的观点，对于这个问题大家是怎么看待的呢？欢迎在下方评论区交流 ~ 我是科技领域创作者，十年互联网从业经验，欢迎关注我了解更多科技知识！

2

因为我是做Java开发的，所以就按照Java的开发流程说一下；首先一个好的API接口，设计是要下功夫的，细节就不在这里说了，这里还是主要说实现；如果开发环境具备，前后大概也就不到十分钟，就可以完成一个简单的API接口的开发（只是个demo）。

0、开发前准备：电脑上需要安装JDK、Maven和IDE。

1、新建一个基于Spring Boot的项目，为了快速完成，我选择登录到【

start.spring.io

】网站上，生成一个项目。通过【Search dependencies to add】可以选择需要引入的包，我这里只引入了Web，也就是Spring MVC；假如你需要通过Mybatis访问数据库，也可以在这里选择；然后点击生成项目。

2、将下载好的项目，解压后引入到你的IDE中，新建一个类：

com.wukong.apidemo.controller

.ApiController

3、在这个类中增加一个方法，并主要使用@RestController、@RequestMapping、@ResponseBody两个标签，整个类大概是这个样子：

4、这时候最简单的一个API接口就完成了，我们可以启动项目后，访问对应的接口地址，得到接口的返回信息：

5、我们再对这个接口稍微加工一些，让swagger帮助我们生成一个接口文档：

5.1、在

pom.xml

中进入swagger需要的包：

5.2、对ApiController增加：@Api、@ApiOperation、@ApiImplicitParams等标签：

5.3、这时候启动项目后，访问：

http://10.141.48.41:8080/swagger-ui.html

5.4、这里留了一个小问题，swagger的配置少了一步，按照上面的做饭，访问swagger的页面是会报404的，大家可以尝试解决。

我将持续分享Java开发、架构设计、程序员职业发展等方面的见解，希望能得到你的关注。

3

1. 首先新建一个项目，然后新建一个Controller类，如下：

2. 然后类上面加上注解@RequestMapping，这个注解要带上一个路径，这个路径会成为接口的一部分，然后再加上@RestController，这个注解是说明接口返回的数据格式为json，因为现在一般都是json数据格式交互

3. 接下来在类里面新建一个方法，如下：

4. 这时候我们还需要在方法上面再加上一个注解@RequestMapping，或者@GetMapping等其他注解

5. 现在基本一个接口就定义完了，我们在方法中加一点信息返回给调用方，如下：

6. 接下来我们启动项目，如下，启动成功

7. 最后我们打开浏览器，访问我们的api接口：

4

API（Application Programming Interface,应用程序编程接口），目的是提供应用程序与开发人员基于某软件或硬件访问获取数据。

api接口的返回数据格式目前来说用的最多的是json数据格式。各个语言实现的方式有所不同，但是api使用者无须关心实现细节。下面是用php实现一个json数据格式的代码，希望对你有所帮助。

PHP简单示例：

假设接口访问地址 http://127.0.0.1/api.php，api.php文件内容是

访问接口 http://127.0.0.1/api.php

特别说明

上术示例只是最最基本的实现方式上的一个小示例！市面上再复杂规范的API，无非就是一个根据客户端的请求参数对数据的筛选。所以这里也给出一个比较规范的API设计思路

1. 使用标准的HTTP方法，规范路由请求。

2. 无状态性，每个请求都是一个新的请求来对待。

3. 支持多种资源表示方式 (xml, json等)。

4. 数据格式规范化，做好数据的安全性。

5

作为BAT的Java开发工程师，来分享下我在公司里写的项目（脱敏）中的封装api接口部分。

我们使用的是SSM框架，但是这里其实不论是SSM还是SSH，抑或是SPRING BOOT，接下来的介绍都是通用的，因为主要是通过介绍注解（annotation），而不是xml文件。

Controller.Class

首先，API接口需要出现在controller层，因此，在类名上方，需要至少两个注解，@controller，用于在项目启动的时候告诉spring，这个类是controller层的，需要加载好；@requestMapping，这个注解相当于指明了api的url中的一部分。

如果一个服务绑定的域名是

http://xx.yy.com

，然后requestMapping中的内容意味着，url为

http://xx.yy.com/dispatch

/.... 格式的请求，会被转发到当前这个类中。

Controller.function

看完接下来我们看函数部分，这里首先也要加一个responseBody注解，这个注解的含义是将controller层中，函数的返回对象通过转换器，转换为指定的格式，写入到http response返回对象的body中去，也就是说下面这个函数返回的String，直接作为response的body内容返回给了用户。

接下来，依旧是requestMapping注解，相信大家也能了解了，复用上面的例子，当url为

http://xx.yy.zz/dispatch/validate

的时候，相当于调用了这个validateParams函数，并且这个请求request的body就会作为body参数，一并传入这个函数。

这里大家可以能注意到了，上面的函数的参数名中用的是requestBody，而下面用的是formParam，虽然二者都是post请求，但是参数接收方式却不一样。这就意味着，代码里指定了不同的接收方式，request的body里也必须用对应的方式才能将数据传递给函数。上图中body用raw形势的就可以，而下图则要求用application/x-www-form-urlencoded格式的body。

最后，上面介绍的都是post请求的api，下图介绍了GET请求的api如何写。可以看出，注解方面，requestMapping里指定requestMethod为GET即可。在函数的参数方面，需要用requestParma注解来接收，如下图。当你发送

http://xx.yy.com

/dispatch/getMyContract?username=xiaomin&password=123 这个请求的时候，就相当于调用了下面的getMyContract函数，并且传入的username参数为xiaomin，password参数为123.

以上是我的浅见，欢迎各位在下方评论区交流点赞。

我是苏苏思量，来自BAT的Java开发工程师，每日分享科技类见闻，欢迎关注我，与我共同进步。

6

API接口是我们在多个模块之间调用、协作是常用的一种方式，大多数编程语言都会考虑到这一点，因此，也都有高效实现API接口的方式，例如，

• Python的flask

• Java的Spring Boot

以Python的flask为例，我们可以轻松实现一个api接口，

Spring Boot实现API接口的示例这里就不展示了，SpringBoot已经把开发流程简化的非常彻底了，比较简单。

这里，针对Python 我推荐一款开发API接口的第三方包，近期非常受欢迎，它就是fastapi。

链接：https://github.com/tiangolo/fastapi

Star：10.4k

fastapi是一款快速、高效的api接口开发工具，它具有如下特性，

快速：非常高的性能，与NodeJS和Go相当（感谢Starlette和Pydantic）。最快的Python框架之一。

• 快速编码：将开发特性的速度提高大约200%到300%。

• 更少的错误：减少大约40%的由人类（开发人员）引起的错误。

• 直观：强大的编辑器支持。到处都是。更少的调试时间。

• 简单：易于使用和学习。减少阅读文档的时间。

• 简而言之：最小化代码重复。每个参数声明有多个特性。

• 健壮：获得生产准备代码，自动交互文档。

• 基于标准：基于（并且完全兼容）api的开放标准。

感兴趣的可以尝试一下。

---

如果觉得有帮助的话，麻烦帮忙点个赞再走吧~

7

以python3 + PostgreSQL 为例：

术语

REST： REpresentational State Transfer

目标

• GET - /api/Category - Retrieve all categories

• POST - /api/Category - Add a new category

• PUT - /api/Category - Update a category

• DELETE - /api/Category - Delete a category

• GET - /api/Comment - Retrieve all the stored comments

• POST - /api/Comment - Add new comment

要求

• python3.*
• PostgreSQL

requirements.txt的内容如下：

• flask - Python的微框架

• flask_restful - 这是Flask的扩展，可快速构建REST API。

• flask_script - 提供了在Flask中编写外部脚本的支持。

• flask_migrate - 使用Alembic的Flask应用进行SQLAlchemy数据库迁移。

• marshmallow - ORM/ODM/框架无关的库，用于复杂数据类型（如对象）和Python数据类型转换。

• flask_sqlalchemy - Flask扩展，增加了对SQLAlchemy的支持。

• flask_marshmallow - 这是Flask和marshmallow的中间层。

• marshmallow-sqlalchemy - 这是sqlalchemy和marshmallow的中间层。

• psycopg - Python的PostgreSQL API。

安装依赖

安装配置PostgreSQL

这里以 Ubuntu 16.04为例：

格式不太好调整， 代码参见本人的博客： https://china-testing.github.io/flask_api.html

imageimage

8

现在的Web开发基本都是多端共用同一Api,也就是当前最流行主导的前后端完全分离的模式去开发Api接口。

而我们通常用的最正规标准的又是Restful Api。就是在定义接口的时候不像以前那样随心所欲的想怎么定义就怎么定义，基本都是按照固定模式，达到见名知意基本不需要看接口注释就知道怎么调用。

就比如，现在大家都默认约定俗成的获取统一用Get请求，新增用Post请求，修改用Patch请求，删除用Delete请求，这样对于接口使用者从接口的请求方式就立马知道什么情况调用哪个指定接口，很方便高效。

9

如果只是一个简单API实例的话，不涉及数据库等，可以实现的语言可以说非常的多，但是我觉得比较简单的是nodejs和go 因为他们有自己的原生服务模块，nodejs有http模块，go有net模块，都直接可以起一个web服务，无需Apache，Tomcat等web服务器

10

API接口设计个人觉得需考虑其扩展性能特别是对外公共接口，否则多个业务需求类似会存在两套API的情况，比较浪费资源。其次api名称，请求参数，返回结果必须有确定含义，容易上手，返回结果一般我设计时分为2部分，系统层面信息，业务层面信息，系统层面例如api调用异常，一般用约定好的错误码标识，业务层面就很宽泛，例如银行业务联网核查，查不到用户信息，从系统层面这是OK的，业务层面肯定是不行的，不可能用户在银行有账户却没有用户信息，当然可能数据库在做迁移导致暂时访问为空，这种业务错误也可以通过状态码或者状态标识boolean值+错误信息返回给客户端，这样api出问题可以快速定位是系统问题还是业务问题