go语言api文档学习 go语言开发api

GO语言（十三）：使用 Go 和 Gin 开发 RESTful API（下）

当客户端在 发出POST请求时/albums，您希望将请求正文中描述的专辑添加到现有专辑数据中。

成都创新互联公司服务项目包括雨花台网站建设、雨花台网站制作、雨花台网页制作以及雨花台网络营销策划等。多年来，我们专注于互联网行业，利用自身积累的技术优势、行业经验、深度合作伙伴关系等，向广大中小型企业、政府机构等提供互联网行业的解决方案，雨花台网站推广取得了明显的社会效益与经济效益。目前，我们服务的客户以成都为中心已经辐射到雨花台省份的部分城市，未来相信会继续扩大服务区域并继续获得客户的支持与信任！

为此，您将编写以下内容：

1、编写代码

a.添加代码以将专辑数据添加到专辑列表。

在此代码中：

1）用于Context.BindJSON 将请求正文绑定到newAlbum。

2） album将从 JSON 初始化的结构附加到albums 切片。

3）向响应添加201状态代码，以及表示您添加的专辑的 JSON。

b.更改您的main函数，使其包含该router.POST函数，如下所示。

在此代码中：

1）将路径中的POST方法与 /albumspostAlbums函数相关联。

使用 Gin，您可以将处理程序与 HTTP 方法和路径组合相关联。这样，您可以根据客户端使用的方法将发送到单个路径的请求单独路由。

a.如果服务器从上一节开始仍在运行，请停止它。

b.从包含 main.go 的目录中的命令行，运行代码。

c.从不同的命令行窗口，用于curl向正在运行的 Web 服务发出请求。

该命令应显示添加专辑的标题和 JSON。

d.与上一节一样，使用curl检索完整的专辑列表，您可以使用它来确认添加了新专辑。

该命令应显示专辑列表。

当客户端向 发出请求时GET /albums/[id]，您希望返回 ID 与id路径参数匹配的专辑。

为此，您将：

a.在您在上一节中添加的函数下方postAlbums，粘贴以下代码以检索特定专辑。

此getAlbumByID函数将提取请求路径中的 ID，然后找到匹配的专辑。

在此代码中：

（1）Context.Param用于从 URL 中检索id路径参数。当您将此处理程序映射到路径时，您将在路径中包含参数的占位符。

（2）循环album切片中的结构，寻找其ID 字段值与id参数值匹配的结构。如果找到，则将该album结构序列化为 JSON，并将其作为带有200 OK HTTP 代码的响应返回。

如上所述，实际使用中的服务可能会使用数据库查询来执行此查找。

（3）如果找不到专辑，则返回 HTTP 404错误。

b.最后，更改您的main，使其包含对router.GET的新调用，路径现在为/albums/:id ，如以下示例所示。

在此代码中：

（1）将/albums/:id路径与getAlbumByID功能相关联。在 Gin 中，路径中项目前面的冒号表示该项目是路径参数。

a.如果服务器从上一节开始仍在运行，请停止它。

b.在包含 main.go 的目录中的命令行中，运行代码以启动服务器。

c.从不同的命令行窗口，用于curl向正在运行的 Web 服务发出请求。

该命令应显示您使用其 ID 的专辑的 JSON。如果找不到专辑，您将收到带有错误消息的 JSON。

恭喜！您刚刚使用 Go 和 Gin 编写了一个简单的 RESTful Web 服务。

本节包含您使用本教程构建的应用程序的代码。

API接口入门（一）：读懂API接口文档

本文目录：

API接口是什么？

为什么我们需要API接口？

API接口的核心

一、API接口是什么？

我们来以一个常见的数学公式理解API，比如y=x+2，当x=2的时候，y=4，对么？

那此时，我们把y=x+2称为接口，x=2称为参数，y=4称为返回结果，那这个接口的功能就是能把我们输入的数加上2（注意：这里你可以发现接口自身是带有逻辑的）。

类比地，我们来理解一个常见的场景，比如现在有一个可以把经纬度转化为城市的接口，那当我输入经度是55°，纬度是88°的时候，接口通过自己的逻辑运算，返回结果告诉我：杭州市。

这样你就可以清晰地了解百度百科的官方解释了，接口就是预先定义的函数逻辑，他是供其他系统请求，然后返回结果的一个东西。

二、为什么我们需要API接口？

背景：我们的业务系统涉及多方多面，如果要一个公司或者一个系统把所有业务都做完，那未免工作量太大了吧？并且如果其他系统或公司有更好的运算逻辑，那我们在设计功能的时候可以考虑利用接口进行开发。

核心需求：利用现有接口可以降低开发成本，缩短开发成本。

举个例子：比如我是打车的APP，现在我需要在我的页面上展现地图的功能，对于我司而言，新做地图功能未免成本过高，那我们可以在高德开放平台或者百度地图的开放平台，找到地图API，这样的话我们只需要购买高德的服务，部署调用高德地图API，这样就可以快速在我们页面上线地图功能了。

三、API接口的核心

对于小白而言，初看API文档可能是一头雾水的——从哪里看，怎么看，看什么是摆在面前的问题。

其实对于产品经理而言，我们应该更关注这个公司可以提供什么样的API接口服务，比如我知道高德可以提供地图API，规划路线的API，这样的话在我们设计功能和工作中就可以想到调用他们的服务或者参考。

所以产品小白们看不懂也不用过于担心，未来工作中你也会更深入了解清楚，因为看懂并不复杂，以下是API接口的核心点，所有的说明文档离不开这5个核心点。

以下说明均以微信开放平台为例说明，文末有各开放平台的地址，大家有空可以去学习。好了，事不宜迟，现在我们来建立一个场景。

我们现在有一个APP，需要用户在购买的时候调起微信支付的API，完成购买。请各位自动进入这个场景，把自己当作一位产品经理。

1. 接口地址

现在Now，用户点击付款，我们需要告诉微信，我们要调起你们的收银台啦！但，去哪里告诉呢？这就需要接口地址了，也就相当于向微信的这条链接传输指定的数据。

一个链接地址不是我们理解的一个页面，你可以理解是一个电话号码，小白们要改变这个观念。

此时我们可以看到接口文档告诉我们链接是如下这条，那我们现在已经拨通微信的电话了。

2. 请求参数（报文）

我们现在需要告诉微信，你想调用收银台对吧。那我们需要写下来，此时生成的叫做报文，也就是你想告诉这个接口的内容是什么？相当于前文函数的输入x=2。

一般来说，报文的格式和内容都是按接口文档规定的。如下文就是微信开放平台对调起收银台的报文要求。

我们先来看前2个参数，你现在跟微信在对话，是不是应该先告诉微信，你是谁？这里微信的文档告诉你应该要用应用ID+商户号来确定你的身份，什么意思呢？

比如你是A商户，下面有a，b，c三个APP，所以微信要知道你是哪个商家，下面的哪个APP要用收银台。这是非常重要的，微信后面要把收到的钱打到对应的账户以及统计数据等。

那我们就在报文里面写下这两句话：

appidwx2421b1c4370ec43b/appid（我的应用ID是wx2421…….）

mch_id10000100/mch_id（我的商户号是10000…….）

好了，现在微信知道你是谁了，那你要告诉微信，你需要微信支付帮你收多少钱对吧？这里定义了货币类型和总金额，也就是收什么货币，收多少钱。

这里你看，货币类型的必填写了否，也就是说你也可以不告诉微信支付货币类型是什么，因为他在后面备注了默认是人民币。

好的，那我们写下两段报文

free_typeCNY/ free_type （我要收人民币）

total_fee1/total_fee（我要收1元）

好了，现在微信知道你是谁，也知道要收多少钱了，那接下来微信支付要把收钱结果告诉你呀，因为你得知道用户是成功支付了才能继续发货，服务啊等等的。所以这里我们用到通知地址，就是告诉微信，等下完事了他去哪里告诉你支付结果。那我们把地址写好：

notify_url;/notify_url

3. 返回结果

刚刚微信支付已经去收款了，现在他要在我们留下的通知地址中，告诉我们结果了。结果无非是两种：成功收款？收款不成功？

（1）成功

很顺利，现在用户成功付钱了，并且微信也把成功的消息告诉我们了，并且他还把用户支付的一些信息也告诉我们。

那这里就是微信支付成功收款后告诉我们的信息。

应用APPID，商户号：告诉你我成功扣款的是哪家商户的哪个APPID的交易。

业务结果：成功或失败

（2）失败

在产品设计的时候，我们往往很关注失败的情况，当收款失败的时候，微信同时会告诉你失败的原因，如下图很好理解，失败的原因有很多很多种，我们在设计的时候往往要分析每种失败的原因，为每个失败的原因设计页面和用户提示，以确保用户能理解。

以上就是API接口基本运作模式的理解，下面我将继续更新API接口的一些更为深入和细节的关键元素，如请求方式/签名/加解密等等。

可供参考的开放平台网站

微信支付：

高德平台开放平台：

小白想学习go语言，哪位有教程？

如果你想每一步走得扎实，那么我的建议如下：

对一名从未接触过程序开发的小白来说，首先得足够了解计算机，至少你得知道你写的代码在计算机内部是如何运行的，你的数据是如何通过网络传输，《微机原理与接口技术》和《TCP/IP详解》（三卷）是很好的学习入门 之选，同时也是很好的参考手册

一切准备就绪，开始写你的第一个程序，建议选C语言，基本的数据结构、指针、函数、循环、条件判断、手动GC等都上手试一遍，做到了然于胸，信手拈来

进入正题，学习Go语言，你会发现，换汤不换药，程序的构成无非那么几类，当然Go会有自己的特性，比如slice、goroutine、channel等，当然这一切得基于go开发环境

至于教程，最合适的莫过于官方文档，老老实实看完，别太在意网上的各种项目实战，先学会走路，再学跑

最重要的一点：纸上得来终觉浅，绝知此事要躬行，多敲敲代码，熟能生巧，happy coding！

如何快速编写api文档

刚开始写接口文档的服务端同学，很容易按着代码的思路去编写接口文档，这让客户端同学或者是服务对接方技术人员经常吐槽，看不懂接口文档。这篇文章提供一个常规接口文档的编写方法，给大家参考。

推荐使用的是docway 写接口文档，方便保存和共享，支持导出PDF MARKDOWN，支持团队项目管理。

一、请求参数

1. 请求方法

GET

用于获取数据

POST

用于更新数据，可与PUT互换，语义上PUT支持幂等

PUT

用于新增数据，可与POST互换，语义上PUT支持幂等

DELETE

用于删除数据

其他

其他的请求方法在一般的接口中很少使用。如：PATCH HEAD OPTIONS

2. URL

url表示了接口的请求路径。路径中可以包含参数，称为地址参数，如**/user/{id}**，其中id作为一个参数。

3. HTTP Header

HTTP Header用于此次请求的基础信息，在接口文档中以K-V方式展示，其中Content-Type则是一个非常必要的header，它描述的请求体的数据类型。

常用的content-type：

application/x-www-form-urlencoded

请求参数使用“”符号连接。

application/json

内容为json格式

application/xml

内容为xml格式

multipart/form-data

内容为多个数据组成，有分隔符隔开

4. HTTP Body

描述http body，依赖于body中具体的数据类型。如果body中的数据是对象类型。则需要描述对象中字段的名称、类型、长度、不能为空、默认值、说明。以表格的方式来表达最好。

示例：

二、响应参数

1. 响应 HTTP Body

响应body同请求body一样，需要描述请清除数据的类型。

另外，如果服务会根据不同的http status code 返回不同的数据结构， 也需要针对不同的http status code对内容进行描述。

三、接口说明

说明接口的应用场景，特别的注意点，比如，接口是否幂等、处理是同步方式还是异步方式等。

四、示例

上个示例（重点都用红笔圈出来，记牢了）：

五、接口工具

推荐使用的是（以前叫小幺鸡） 写接口文档，方便保存和共享，支持导出PDF MARKDOWN，支持团队项目管理。

请教在线文档的api

Android中文版

api手册地址：

Ant最新版

api手册地址：

ASM字节码操作

api手册地址：

Axis2最新版

api手册地址：

Bash脚本

api手册地址：

Bootstrap 3

api手册地址：

Bootstrap 4

api手册地址：

C/C++

api手册地址：

C3P0连接池

api手册地址：

CentOS使用文档

api手册地址：

Commons-Beanutils

api手册地址：

Commons-Fileupload

api手册地址：

Commons-IO最新版

api手册地址：

Commons-Lang最新版

api手册地址：

Commons-Net最新版

api手册地址：

CSS 3

api手册地址：

DBCP连接池

api手册地址：

Dom4j

api手册地址：

dubbo中文文档

api手册地址：

EhCache

api手册地址：

Freemarker

api手册地址：

Go语言

api手册地址：

Hadoop

api手册地址：

Hibernate中文版

api手册地址：

IKAnalyzer中文版

api手册地址：

Java 10

api手册地址：

Java 6

api手册地址：

Java 7

api手册地址：

Java 8中文版

api手册地址：

jqGrid中文版

api手册地址：

Jquery中文版

api手册地址：

Json-lib

api手册地址：

Junit4最新版

api手册地址：

Kryo

api手册地址：

Log4j最新版

api手册地址：

Lucene

api手册地址：

Maven

api手册地址：

Windows MFC中文版

api手册地址：

Mybatis

api手册地址：

MySql中文版

api手册地址：

Netty 3.6

api手册地址：

Nginx中文版

api手册地址：

OpenJPA最新版

api手册地址：

PHP中文版

api手册地址：

POI-apache

api手册地址：

QuickServer

api手册地址：

redis中文参考文档

api手册地址：

Ruby

api手册地址：

Ruby-library

api手册地址：

Ruby on Rails

api手册地址：

Shiro

api手册地址：

Spring最新版

api手册地址：

Spring for Android

api手册地址：

Spring Boot

api手册地址：

Spring Cloud中文文档

api手册地址：

Spring Security

api手册地址：

Spring中文版

api手册地址：

Struts 2最新版

api手册地址：

Taperstry

api手册地址：

TensorFlow中文

api手册地址：

Tomcat

api手册地址：

Ubuntu

api手册地址：

Velocity 1.7

api手册地址：

VelocityTools2.0

api手册地址：

Vue Router中文参考

api手册地址：

vue.js中文文档

api手册地址：

XMLBeans

api手册地址：

Yahoo UI中文版

api手册地址：

Zend Framework中文版

api手册地址：

Zookeeper

api手册地址：

如何开始自学api编程?？？

首先你先把API的概念搞清楚，API的全称我想你应该略有了解，哪怕全称记不住：Application Programming Interface，应用程序编程接口

说白了就是别人帮你写好了一个功能，封装成类或是函数，这就叫API，你自己写了个类，这也可以是API。

一般知名框架与库都是会有开发文档的，对着文档写代码调用里面的功能就可以了，没文档就只能硬啃代码了，这没办法，除非有人知道并告诉你了该怎么用。

我们接触最多的其实还是系统API，比如你用的是Python，那我就拿Python举例子，里面有一个包叫os，看名字就知道了全称是Operation System，执行系统操作的。sys模块用于与解释器的交互的，这些都是系统库，或是叫系统模块，当然这个系统所指范围有点广。

不知道我所理解的API是否正确的，一直感觉自己理解的是错误的，或是片面的，请各位大神轻喷。。。