博客项目（一）：API说明文档、用户模块、短信模块、支付模块

一、概述：

随着近期公司内部个人兴趣社区活动的如火如荼，为满足广大社区爱好者追求自我的梦想，特此开发内部博客；方便大家整理及自己社区活动中的一些优质内容，增加社区的互动性。此文档为博客项目的API详情。

注：实际开发中会根据模块书写文档。

二、事件定义：

2.1 注册

• 新用户可通过此功能注册为内部论坛的注册用户。
• 每个注册用户可申请一个自己独立的博客空间，只有注册用户方可在自己的博客中发表自己的博客及在博客内容上留言及回复他人的留言。

2.2 登陆

• 用户可通过此功能进行用户登陆操作，只有登陆的用户方可执行会员的相关操作
• 如：发布博客及留言功能。

2.3 修改个人信息

• 每个注册用户都有 个人描述，个人签名及头像和昵称 可供自定义编写；
• 用户需要进行登陆后，方可使用该功能。

三、开发规范:

3.1 后端环境

Python 3.7.3 + django 2.2.12 + mysql 5.5 + Ubuntu18.04 + vim + Pycharm + Redis

3.2 通信协议

http

3.3 通信格式

json

3.4 API规范

一定程度上符合RESTful 定义

四、用户模块

4.1 数据库结构：

字段名	类型	作用	备注1	备注2
username	varchar(11)	用户名	注册时填写的用户名，不可修改	主键
nickname	varchar(30)	昵称	在博客中显示的名字，可修改	无
email	varchar(50)	邮箱	预留	无(Emailfield())
phone	varchar(11)	手机号	无	无
password	varchar(32)	密码	用户密码，已散列存储	无
sign	varchar(50)	个人签名	无	无
info	varchar(150)	个人描述	无	无
avatar	varchar(100)	头像	无	无(ImageField)
created_time	datetime	创建时间	无	无
updated_time	datetime	更新时间	无	无

# user/models.py 
from django.db import models
import random


def default_sign():
    signs = ["我的签名我做主", "键盘敲烂，薪资过万", "不要迷恋哥，哥只是个传说"]
    return random.choice(signs)


# Create your models here.
class UserProfile(models.Model):
    username = models.CharField(verbose_name="用户名", max_length=11, primary_key=True)
    nickname = models.CharField(verbose_name="昵称", max_length=30)
    password = models.CharField(verbose_name="密码", max_length=32)
    email = models.EmailField(verbose_name="邮件")
    phone = models.CharField(verbose_name="手机号", max_length=11)
    avatar = models.ImageField(upload_to="avatar", verbose_name="图像", null=True)
    sign = models.CharField(verbose_name="个人签名", max_length=50, default=default_sign)
    info = models.CharField(verbose_name="个人描述信息", max_length=150, default="")
    created_time = models.DateTimeField(auto_now_add=True)
    updated_time = models.DateTimeField(auto_now=True)

    class Meta:
        db_table = "user_user_profile"

4.2 接口说明

4.2.1 注册接口：

• URL：http://127.0.0.1:8000/v1/users

4.2.1.1 请求方式：

POST

4.2.1.2 请求格式：

json 具体参数如下：

字段	含义	类型	备注
username	用户名	char	必填
email	用户邮箱	char	必填
password1	第一次输入的密码	char	必填
password2	第二次输入的密码	char	必填

请求示例：

{
    'username': jack, 
    'email': ['abc@qq.com',](mailto:'abc@qq.com',) 
    'password1': 'abcdef', 
    'password2': 'abcdef'
}

4.2.1.3 响应格式：

json 具体参数如下：

字段	含义	类型	备注
code	状态	int	默认正常为200，异常请见1.4
username	用户名	char	无
data	返回具体的数据都包含在data中	{}	{token: xxxx 此为会话保持用的令牌-char }

响应示例：

{
    'code': 200 ,
    'username': 'abc',
    'data': {
        'token': 'asdadasd.cvreijvd.dasdadad'
    } 
}

4.2.1.4 异常码：

异常码	含义	备注
202	请求中无内容
203	请求中未提交用户名
204	请求中未提交邮箱
205	请求中未提交密码
206	两次提交的密码不一致	即password1 != password2
207	用户名已存在
500	服务器异常

异常响应示例

{
    'code':203,  
    'error':u'请输入用户名'
}

4.2.2 获取用户数据接口

• URL：http://127.0.0.1:8000/v1/users/<username>

4.2.2.1 请求方式：

GET

4.2.2.2 请求格式:

1. 直接GET请求，可获取全量数据
2. GET请求后添加查询字符串，可根据具体查询字符串查询：http://127.0.0.1:8000/v1/users/?nickname=1

4.2.2.3 响应格式：

json 具体参数如下

字段	含义	类型	备注
code	状态	int	请求成功，code为200，异常码请见2.4
username	用户名	char	此次欲获取的用户的用户名
data	返回的具体数据均在data里	{}	{‘info’:个人描述-char，‘sign’:个人签名-char, ‘nickname’:昵称-char, ‘avatar’: 头像地址-char}

响应示例：

全量响应：

{'code':200,'username':'xiaoming','data':{'nickname':'abc', 'sign':'hellow', 'avatar': 'abc.jpg', 'info': 'hahahahah'}}

局部响应（GET请求添加查询字符串- 以下为查询nickname的返回）:

{'code':200, 'username':'123', 'data':{'nickname':'abcde'} }

4.2.2.4 异常码：

异常码	含义	备注
208	用户名不存在

4.2.3 修改用户个人信息接口

• URL：http://127.0.0.1:8000/v1/users/<username>

4.2.3.1 请求方式：

PUT

4.2.3.2 请求格式

json 具体参数如下

字段	含义	类型	备注
sign	个人签名	char	非必填
info	个人描述	char	非必填
nickname	昵称	char	非必填

该请求需客户端在HTTP header 里添加 token, 格式如下：

Authorization ： token

请求示例：

{'sign':xxx, 'info':xxxx, 'nickname':xxxx}

4.2.3.3 响应格式：

json , 具体参数如下

字段	含义	类型	备注
code	状态	Int	正常为200，异常码见3.4
username	用户名	char	此次请求的用户名

响应示例：

{'code':200, 'username':'char'}

4.2.3.4 异常码：

异常码	含义	备注
202	空提交	请求中无任何信息

异常响应示例:

{'code':202, 'error': 'please put data'}

4.2.4 上传头像接口

URL:http://127.0.0.1:8000/v1/users/<username>/avatar

4.2.4.1 请求方式

POST multipart/form-data

4.2.4.2 请求格式

表单 具体表单参数如下

字段	含义	类型	备注
avatar	表单中的图片	char	必填

该请求需客户端在HTTP header 里添加 token, 格式如下：

Authorization ： token

4.2.4.3 响应格式

json, 具体参数如下

字段	含义	类型	备注
code	状态	Int	正常为200
username	用户名	char	此次请求的用户名

4.2.5 获取token

【即登陆请求】 http://127.0.0.1:8000/v1/tokens

4.2.4.1 请求方式

POST

4.2.4.2 请求格式

json , 具体参数如下

字段	含义	类型	备注
username	用户名	char	必填
password	密码	char	必填

请求示例：

 {"username": "xxx", "password": "yyy"}

4.2.4.3 响应格式

json, 具体参数如下

字段	含义	类型	备注
code	200	Int	正常为200，异常码请见5.4
username	用户名	char
data	返回具体数据都在data中	{}	{‘token’: ‘xxxx’-char}

响应示例：

{"code": 200,"username": "asc", "data": {"token": "zdsadasd"}}

4.2.4.4 异常码

异常码	含义	备注
201	请求方式并非POST
202	请求为空
203	请求中未提交用户名
205	请求中未提交密码
208	用户名不存在
209	提交的密码不正确

异常码响应示例

{"code": 205, "error": "no password"}

五、短信模块

5.1 业务流程说明

5.2 Base URL

模板短信API引用的地址有Base URL。

生产环境的Base URL：https://app.cloopen.com:8883
注意：为了确保数据隐私，云通讯平台的REST API是通过HTTPS方式请求。

5.3 业务URL

业务URL格式：/2013-12-26/Accounts/{accountSid}/SMS/{funcdes}?sig={SigParameter}

在URL格式中 {}内的内容表示为参数，非{}的内容固定不变。
Base URL与业务URL相拼接为完整请求URL，完整URL示例：

https://app.cloopen.com:8883/2013-12-26/Accounts/abcdefghijklmnopqrstuvwxyz012345/SMS/TemplateSMS?sig=C1F20E7A9733CE94F680C70A1DBABCD

属性说明：

属性	类型	约束	说明
accountSid	String	必选	开发者主账户ACCOUNT SID（登陆官网在管理控制台获取）
SigParameter	String	必选	REST API 验证参数，生成规则如下:1.使用MD5加密（账户Id + 账户授权令牌 + 时间戳）。其中账户Id和账户授权令牌根据url的验证级别对应主账户。时间戳是当前系统时间，格式"yyyyMMddHHmmss"。时间戳有效时间为24小时，如：20140416142030;2.SigParameter参数需要大写，如不能写成sig=abcdefg而应该写成sig=ABCDEFG

5.4 HTTP标准包头字段

Accept:application/xml;

Content-Type:application/xml;charset=utf-8;

Content-Length:256;

Authorization:

属性说明:

属性	类型	约束	说明
Accept	String	必选	客户端响应接收数据格式：application/xml、application/json
Content-Type	String	必选	类型：application/xml;charset=utf-8、application/json;charset=utf-8
Content-Length	String	必选	Content-Length
Authorization	String	必选	验证信息，生成规则详见下方说明1.==使用Base64编码（账户Id + 冒号 + 时间戳）==其中账户Id根据url的验证级别对应主账户2.冒号为英文冒号3.时间戳是当前系统时间，格式"yyyyMMddHHmmss"，需与SigParameter中时间戳相同。

5.5 发送模板短信接口

5.5.1 请求地址

POST /2013-12-26/Accounts/{accountSid}/SMS/TemplateSMS?sig={SigParameter}

5.5.2 请求包体

属性	类型	约束	说明
to	String	必选	短信接收端手机号码集合，用英文逗号分开，每批发送的手机号数量不得超过200个
appId	String	必选	应用Id，官网控制台应用列表获取
templateId	String	必选	模板Id，官网控制台模板列表获取。测试模板id是1。测试模板的内容是：【云通讯】您使用的是云通讯短信模板，您的验证码是{1}，请于{2}分钟内正确输入
datas	Array	可选	内容数据外层数组节点
data	String	可选	内容数据，用于替换模板中{序号}，模板如果没有变量，此参数可不传，多个变量，使用数组的数据格式
subAppend	String	可选	扩展码，四位数字 0~9999
reqId	String	可选	第三方自定义消息id，最大支持32位，同账号下同一自然天内不允许重复。

XML请求示例

 POST /2013-12-26/Accounts/abcdefghijklmnopqrstuvwxyz012345/SMS/TemplateSMS?sig=
 C1F20E7A9733CE94F680C70A1DBABCDE HTTP/1.1
 Host:192.168.0.1:8883
 content-length: 139
 Accept:application/xml; 
 Content-Type:application/xml;charset=utf-8; 
 Authorization:ZmY4MDgwODEzYzM3ZGE1MzAxM2M4MDRmODA3MjAwN2M6MjAxMzAyMDExNTABCDE=
 <?xml version='1.0' encoding='utf-8'?> 
 <TemplateSMS>
  <to>13912345678</to>
  <appId>ff8080813c37da53013c3054f567007e</appId> 
  <templateId>1</templateId>
  <reqId>abc123</reqId>
  <subAppend>8888</subAppend>
  <datas>
    <data>替换内容</data>
    <data>替换内容</data>
  </datas>
 </TemplateSMS>            

JSON请求示例

 POST /2013-12-26/Accounts/abcdefghijklmnopqrstuvwxyz012345/SMS/TemplateSMS?sig=
 C1F20E7A9733CE94F680C70A1DBABCDE HTTP/1.1
 
 Host:192.168.0.1:8883
 content-length: 139
 Accept:application/json; 
 Content-Type:application/json;charset=utf-8; 
 Authorization:ZmY4MDgwODEzYzM3ZGE1MzAxM2M4MDRmODA3MjAwN2M6MjAxMzAyMDExNTABCDE=
 
 {"to":"13911281234,15010151234,13811431234","appId":"ff8080813fc70a7b013fc72312324213","reqId":"abc123","subAppend":"8888","templateId":"1","datas":["替换内容","替换内容"]}           

5.5.3 响应包体

此步响应只表明接口请求成功，不代表短信已送达手机。具体送达状态请参考“状态报告部分”
对响应解析后，statusCode为"000000"表示请求发送成功。statusCode非"000000"表示请求发送失败，客户服务端可以根据自己的逻辑进行重发或者其他处理。

属性	类型	约束	说明
statusCode	String	必选	请求状态码，取值000000（成功），其余状态码含义详见短信错误码部分
smsMessageSid	String	必选	短信唯一标识符
dateCreated		String	必选

XML响应示例

  HTTP/1.1 200 OK 
  Content-Length: 641 
  
  <?xml version="1.0" encoding="UTF-8" standalone="yes"?&;
  <Response>
   <statusCode>000000</statusCode>
    <TemplateSMS>
      <smsMessageSid>ff8080813c373cab013c94b0f0512345</smsMessageSid>
      <dateCreated>20130201153809</dateCreated>
    </TemplateSMS>
  </Response>          

JSON响应示例

 HTTP/1.1 200 OK 
 Content-Length: 641
 
 {"statusCode":"000000","templateSMS":{"dateCreated":"20130201155306","smsMessageSid":" ff8080813c373cab013c94b0f0512345"}}        

六、支付模块

6.1 注册开发者账号

​ 调试支付宝支付需要先 在 支付宝开放平台 进行注册，入驻为 “自助研发者”；链接为 https://open.alipay.com/platform/home.htm

​ 第一次进入需要填写详细信息 - 注意：切换为 自研开发者

6.2 进入沙箱

完善个人信息后，在个人管理后台可看到 “沙箱” 服务

注：沙箱为支付宝提供的调试支付的测试环境，在该环境下，可模拟和调试支付流程

具体位置如下： 开发者中心 - 首页

6.3 查看沙箱

点击 研发服务 - 进入沙箱后， 在沙箱应用选项中可以看到支付宝提供的测试应用

注：当您的网站上线运营时，需要在开放平台申请一个应用；并填写相关信息审核后，方可使用支付功能；沙箱应用为支付宝提供开发者测试用的应用

6.4 生成&添加 RSA 公私钥

6.4.1 生成钥匙

支付过程中涉及到请求和响应的签名校验；

在linux终端中 输入openssl 进入 交互环境

tarena@tedu:~$openssl
OpenSSL> genrsa -out app_private_key.pem 2048   #私钥
OpenSSL> rsa -in app_private_key.pem -pubout -out app_public_key.pem               #导出公钥
OpenSSL> exit
tarena@tedu:~$ls
    app_private_key.pem   app_public_key.pem

RSA 钥匙用途

公钥加密/私钥解密

私钥签名/公钥验签

6.4.2 添加公钥

点击 沙箱应用展示信息页中的 RSA2密钥 的 设置/查看

在弹出的对话框中，选择 公钥 模式

并将您刚才生成出的 app_public_key.pem 中的内容 复制到 红色大框体内，并保存复制

注意，生成公钥如下, 只复制 -----BEGIN PUBLIC KEY----- 和 -----END PUBLIC KEY----- 之间的内容即可

-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA871I3CXvQWXcbwbcyEJB
r7Prxfhf34z1lzZWEaeBugCiUNjK2llrVKyV5tcHqxv9xTzQXz6Mg4n0jmhqkqtI
B6gCNAo5bYMN9nDRnqZ33ojJmZMmxupWUZCvz+3Svft0P0hd/oKc0OZOTI8MPPNV
y5HsovhABUfVsTgSH/AlMoKEz7sM7Cqtb2LT8nZewSdrnEhLrw7KFkDyNfftO8CF
yls6MbNeI4CHmc0PTcXJ7O8+Fx0WOJrYDKPMHW25OxB1IT3Pdn8PnAbtYeRoiUU1
Yfp/qZMmnedZgF0Qpr+ZIZLPhAZrRwqfMcfSIiNJvmcsUKVGLBal10frAIztHKmW
eQIDAQAB
-----END PUBLIC KEY-----

6.4.3 保存支付宝公钥

提交我方公钥后，弹框会显示 支付宝公钥；该公钥需要复制保存下来；

保存流程如下：

1，用户目录下  
vim alipay_public_key.pem

2，进入vim后手动添加如下两行
-----BEGIN PUBLIC KEY-----
-----END PUBLIC KEY-----

3，光标在BEGIN处 点击 键盘o  进入插入模式，此时光标停留在 BEGIN和END的两行之间；粘贴支付宝公钥  最终格式如下

-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAgVjSs4PrjOsJ/c/m7SDYoPKPIwvEwq3U6p2dzpB0X/wVsYsZEHLrWEeVZfTHi9J0yrvwnxgUPlCGKv4EaJuc8msWuuH3TxEvurTPJxYUCOiBIQYeG5iRTh3fWyCkMlLNm8UXv0v+KRVK9bZ17cWB0vBM7iwrytGbfKg0vhIjsybbOd4VM/m4bWZOFdkXAmJfbO+pfMsa9TzF5zYmSpoHuBAkGu9m7EtzzBlXifthYkhvyEAX/XWG3rgaEe+l8W+NlPZ1uudZ2AIWLvnLl5Jjrcz1yMJqOhsobBrPiWbnwnRsMz1Sn9W9rl/cGITcboPlEMgs988Vcd/o21gHDNwNKQIDAQAB
-----END PUBLIC KEY-----

4，esc退出插入模式， 执行 :wq 退出保存 

6.4.5 安装 python 的 支付宝组件

# 安装python-alipay-sdk
sudo pip3 install python-alipay-sdk -i https://pypi.tuna.tsinghua.edu.cn/simple

#安装成功后执行如下命令 校验安装结果
tarena@tedu:~$ pip3 freeze|grep -i ali
python-alipay-sdk==2.0.1 #输出此结果 则表示安装成功

关于return_url和notify_url的问题

• return_url 【GET】

  • 如果不给return_url支付宝处理完业务会留在自己的网页不做跳转
  • 重定向时会带上订单编号等参数

• notify_url 【POST】

  • 支付结果异步通知

  • 对于 PC 网站支付的交易，在用户支付完成之后，支付宝会根据 API 中商户传入的 notify_url，通过 POST 请求的形式将支付结果作为参数通知到商户系统。

  • 详见https://docs.open.alipay.com/270/105902/

代码演示

6.5 正式接入支付宝

当您在沙箱环境测试完毕后，且您的网站基础功能均已开发完毕，需要在支付宝开放平台 申请应用 方可 正式接入到支付宝

6.5.1 创建应用

开放平台首页- 创建应用 - 网页&移动应用 - 支付接入

6.5.2 填写应用信息

填写应用相关信息后 点击 - 确认创建

6.5.3 签约 快捷即时到账 功能

快捷即时到账 即为 支付宝的 网页支付功能，该功能需要 在应用显示页面手动添加才可支持

步骤1 点击 添加能力

步骤2 选择 快捷即时到账

6.5.4 添加公钥 - 同 沙箱流程

在当前应用信息显示页下方，设置 接口加签方式