文章目录
- 一、概述:
- 二、事件定义:
* - 2.1 注册
- 2.2 登陆
- 2.3 修改个人信息
- 三、开发规范:
* - 3.1 后端环境
- 3.2 通信协议
- 3.3 通信格式
- 3.4 API规范
- 四、用户模块
* - 4.1 数据库结构:
- 4.2 接口说明
–- 4.2.1 注册接口:
+ - 4.2.1.1 请求方式:
- 4.2.1.2 请求格式:
- 4.2.1.3 响应格式:
- 4.2.1.4 异常码:
- 4.2.2 获取用户数据接口
+ - 4.2.2.1 请求方式:
- 4.2.2.2 请求格式:
- 4.2.2.3 响应格式:
- 4.2.2.4 异常码:
- 4.2.3 修改用户个人信息接口
+ - 4.2.3.1 请求方式:
- 4.2.3.2 请求格式
- 4.2.3.3 响应格式:
- 4.2.3.4 异常码:
- 4.2.4 上传头像接口
+ - 4.2.4.1 请求方式
- 4.2.4.2 请求格式
- 4.2.4.3 响应格式
- 4.2.5 获取token
+ - 4.2.4.1 请求方式
- 4.2.4.2 请求格式
- 4.2.4.3 响应格式
- 4.2.4.4 异常码
- 4.2.1 注册接口:
- 五、短信模块
* - 5.1 业务流程说明
- 5.2 Base URL
- 5.3 业务URL
- 5.4 HTTP标准包头字段
- 5.5 发送模板短信接口
– - 六、支付模块
* - 6.1 注册开发者账号
- 6.2 进入沙箱
- 6.3 查看沙箱
- 6.4 生成&添加 RSA 公私钥
– - 6.5 正式接入支付宝
–
一、概述:
随着近期公司内部个人兴趣社区活动的如火如荼,为满足广大社区爱好者追求自我的梦想,特此开发内部博客;方便大家整理及自己社区活动中的一些优质内容,增加社区的互动性。此文档为博客项目的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备注2usernamevarchar(11)用户名注册时填写的用户名,不可修改主键nicknamevarchar(30)昵称在博客中显示的名字,可修改无emailvarchar(50)邮箱预留无(Emailfield())phonevarchar(11)手机号无无passwordvarchar(32)密码用户密码,已散列存储无signvarchar(50)个人签名无无infovarchar(150)个人描述无无avatarvarchar(100)头像无无(ImageField)created_timedatetime创建时间无无updated_timedatetime更新时间无无
from django.db import models
import random
def default_sign():
signs = ["我的签名我做主", "键盘敲烂,薪资过万", "不要迷恋哥,哥只是个传说"]
return random.choice(signs)
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.4username用户名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 != password2207用户名已存在500服务器异常
异常响应示例
{
'code':203,
'error':u'请输入用户名'
}
4.2.2 获取用户数据接口
- URL:
http://127.0.0.1:8000/v1/users/<username></username>
4.2.2.1 请求方式:
GET
4.2.2.2 请求格式:
- 直接GET请求,可获取全量数据
- GET请求后添加查询字符串,可根据具体查询字符串查询:
http://127.0.0.1:8000/v1/users/?nickname=1
4.2.2.3 响应格式:
json 具体参数如下
字段含义类型备注code状态int请求成功,code为200,异常码请见2.4username用户名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></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.4username用户名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</username>
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正常为200username用户名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, 具体参数如下
字段含义类型备注code200Int正常为200,异常码请见5.4username用户名chardata返回具体数据都在data中{}{‘token’: ‘xxxx’-char}
响应示例:
{"code": 200,"username": "asc", "data": {"token": "zdsadasd"}}
4.2.4.4 异常码
异常码含义备注201请求方式并非POST202请求为空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
属性说明:
属性类型约束说明accountSidString必选开发者主账户ACCOUNT SID(登陆官网在管理控制台获取)SigParameterString必选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:
属性说明:
属性类型约束说明AcceptString必选客户端响应接收数据格式:application/xml、application/jsonContent-TypeString必选类型:application/xml;charset=utf-8、application/json;charset=utf-8Content-LengthString必选Content-LengthAuthorizationString必选验证信息,生成规则详见下方说明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 请求包体
属性类型约束说明toString必选短信接收端手机号码集合,用英文逗号分开,每批发送的手机号数量不得超过200个appIdString必选应用Id,官网控制台应用列表获取templateIdString必选模板Id,官网控制台模板列表获取。测试模板id是1。测试模板的内容是:【云通讯】您使用的是云通讯短信模板,您的验证码是{1},请于{2}分钟内正确输入datasArray可选内容数据外层数组节点dataString可选内容数据,用于替换模板中{序号},模板如果没有变量,此参数可不传,多个变量,使用数组的数据格式subAppendString可选扩展码,四位数字 0~9999reqIdString可选第三方自定义消息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=
<TemplateSMS>
<to>13912345678to>
<appId>ff8080813c37da53013c3054f567007eappId>
<templateId>1templateId>
<reqId>abc123reqId>
<subAppend>8888subAppend>
<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″表示请求发送失败,客户服务端可以根据自己的逻辑进行重发或者其他处理。
属性类型约束说明statusCodeString必选请求状态码,取值000000(成功),其余状态码含义详见短信错误码部分smsMessageSidString必选短信唯一标识符dateCreatedString必选
XML响应示例
HTTP/1.1 200 OK
Content-Length: 641
<?xml version="1.0" encoding="UTF-8" standalone="yes"?&;
>
<statusCode>000000statusCode>
<TemplateSMS>
<smsMessageSid>ff8080813c373cab013c94b0f0512345smsMessageSid>
<dateCreated>20130201153809dateCreated>
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—– 之间的内容即可
6.4.3 保存支付宝公钥
提交我方公钥后,弹框会显示 支付宝公钥;该公钥需要复制保存下来;
保存流程如下:
1,用户目录下
vim alipay_public_key.pem
2,进入vim后手动添加如下两行
3,光标在BEGIN处 点击 键盘o 进入插入模式,此时光标停留在 BEGIN和END的两行之间;粘贴支付宝公钥 最终格式如下
4,esc退出插入模式, 执行 :wq 退出保存
6.4.5 安装 python 的 支付宝组件
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 添加公钥 – 同 沙箱流程
在当前应用信息显示页下方,设置 接口加签方式
Original: https://blog.csdn.net/m0_53077537/article/details/120770226
Author: m0_53077537
Title: 博客项目(一):API说明文档、用户模块、短信模块、支付模块
原创文章受到原创版权保护。转载请注明出处:https://www.johngo689.com/735444/
转载文章受原作者版权保护。转载请注明原作者出处!