房贷计算器小程序 API 接口设计方案
统一响应格式
所有API接口均返回以下统一格式的JSON数据：
{ "code": 0, // 状态码，0表示成功，其他值表示失败 "msg": "操作成功", // 响应消息 "data": {} // 响应数据，具体格式根据接口不同而不同}
错误码定义
错误码描述
0成功
-1通用错误
400请求参数错误
401未授权或token无效
403权限不足
404资源不存在
500服务器内部错误
1001用户不存在
1002登录失败
2001贷款计算参数错误
2002贷款计算失败
3001历史记录不存在
3002历史记录保存失败
4001对比记录创建失败
4002对比记录不存在
1. 用户相关接口
1.1 用户登录/注册 API
URL: /v1/user/login
方法: POST
请求参数:
{ "code": "微信登录code", "userInfo": { "nickName": "用户昵称", "avatarUrl": "头像URL" }}
响应数据:
{ "code": 0, "msg": "登录成功", "data": { "userId": 1, "openId": "微信openId", "nickName": "用户昵称", "avatarUrl": "头像URL", "token": "身份认证令牌" }}
1.2 获取用户信息 API
URL: /v1/user/info
方法: GET
请求头: Authorization: Bearer {token}
响应数据:
{ "code": 0, "msg": "获取成功", "data": { "userId": 1, "nickName": "用户昵称", "avatarUrl": "头像URL" }}
1.3 更新用户信息 API
URL: /v1/user/update
方法: PUT
请求头: Authorization: Bearer {token}
请求参数:
{ "nickName": "新昵称", "avatarUrl": "新头像URL"}
响应数据:
{ "code": 0, "msg": "更新成功", "data": { "userId": 1, "nickName": "新昵称", "avatarUrl": "新头像URL" }}
2. 贷款计算相关接口
2.1 贷款计算 API
URL: /v1/loan/calculate
方法: POST
请求头: Authorization: Bearer {token}
请求参数:
{ "type": "commercial", // 贷款类型：commercial-商业贷款，fund-公积金贷款，combined-组合贷款 "repaymentType": "equal", // 还款方式：equal-等额本息，principal-等额本金，compare-对比两种方式 "years": 20, // 贷款年限 // 商业贷款或公积金贷款参数 "amount": 100, // 贷款金额(万元)，type为commercial或fund时必填 "rate": 3.8, // 贷款利率(%)，type为commercial或fund时必填 "basisPoints": 0, // 基点调整，type为commercial时可选 // 组合贷款参数 "commercialAmount": 70, // 商业贷款金额(万元)，type为combined时必填 "commercialRate": 3.8, // 商业贷款利率(%)，type为combined时必填 "commercialBasisPoints": 0, // 商业贷款基点调整，type为combined时可选 "fundAmount": 30, // 公积金贷款金额(万元)，type为combined时必填 "fundRate": 3.1 // 公积金贷款利率(%)，type为combined时必填}
响应数据:
{ "code": 0, "msg": "计算成功", "data": { "loanType": "commercial", // 贷款类型 "repaymentType": "equal", // 还款方式 "years": 20, // 贷款年限 "totalAmount": 100, // 总贷款金额(万元) // 商业贷款或公积金贷款信息 "amount": 100, // 贷款金额(万元) "rate": 3.8, // 贷款利率(%) "adjustedRate": 3.8, // 调整后的利率(%) // 组合贷款信息(type为combined时返回) "commercialAmount": 0, // 商业贷款金额(万元) "commercialRate": 0, // 商业贷款利率(%) "adjustedCommercialRate": 0, // 调整后的商业贷款利率(%) "fundAmount": 0, // 公积金贷款金额(万元) "fundRate": 0, // 公积金贷款利率(%) // 等额本息结果(repaymentType为equal或compare时返回) "equalResult": { "totalLoan": 1000000, // 贷款总额(元) "totalRepayment": 1456783.25, // 还款总额(元) "totalInterest": 456783.25, // 总利息(元) "monthlyPayment": 6069.93 // 月供(元) }, // 等额本金结果(repaymentType为principal或compare时返回) "principalResult": { "totalLoan": 1000000, // 贷款总额(元) "totalRepayment": 1395833.33, // 还款总额(元) "totalInterest": 395833.33, // 总利息(元) "firstMonthPayment": 8166.67, // 首月还款(元) "decreasePerMonth": 31.67, // 每月递减(元) "lastMonthPayment": 4198.33 // 末月还款(元) }, // 对比结果(repaymentType为compare时返回) "interestDiff": 60949.92, // 利息差额(元) // 历史记录ID(系统自动保存) "recordId": 123 // 自动保存的历史记录ID }}
注意: 该接口会自动将计算结果保存到用户的历史记录中，无需再调用单独的保存接口。
2.2 获取默认利率和利率选项 API
URL: /v1/loan/rate-options
方法: GET
响应数据:
{ "code": 0, "msg": "获取成功", "data": { "commercialLprShort": [ {"label": "2025最新LPR 1-5年", "value": 3.95}, {"label": "LPR 1-5年 2024", "value": 3.95}, {"label": "LPR 1-5年 2023", "value": 4.20} ], "commercialLprLong": [ {"label": "2025最新LPR 5年以上", "value": 4.20}, {"label": "LPR 5年以上 2024", "value": 4.20}, {"label": "LPR 5年以上 2023", "value": 4.45} ], "fundRateShort": [ {"label": "公积金利率 1-5年 2025", "value": 2.60}, {"label": "公积金利率 1-5年 2024", "value": 2.60}, {"label": "公积金利率 1-5年 2023", "value": 2.75} ], "fundRateLong": [ {"label": "公积金利率 5年以上 2025", "value": 3.10}, {"label": "公积金利率 5年以上 2024", "value": 3.10}, {"label": "公积金利率 5年以上 2023", "value": 3.25} ], "defaultCommercialRateShort": 3.95, "defaultCommercialRateLong": 4.20, "defaultFundRateShort": 2.60, "defaultFundRateLong": 3.10 }}
3. 历史记录相关接口
3.1 保存计算记录 API
URL: /v1/history/save
方法: POST
请求头: Authorization: Bearer {token}
请求参数: 与贷款计算API的请求参数相同，但增加计算结果
{ "params": { // 与贷款计算API的请求参数相同 }, "results": { // 与贷款计算API的响应数据相同 }}
响应数据:
{ "code": 0, "msg": "保存成功", "data": { "recordId": 1 // 记录ID }}
3.2 获取历史记录列表 API
URL: /v1/history/list
方法: GET
请求头: Authorization: Bearer {token}
请求参数:
page: 1 // 页码，默认1
pageSize: 10 // 每页条数，默认10
响应数据:
{ "code": 0, "msg": "获取成功", "data": { "total": 25, // 总记录数 "pages": 3, // 总页数 "currentPage": 1, // 当前页码 "pageSize": 10, // 每页条数 "list": [ { "id": 1, // 记录ID "date": "2023-05-20 14:30:25", // 创建日期 "loanTypeText": "商业贷款", // 贷款类型文本 "totalAmount": 100, // 贷款总额(万元) "years": 20, // 贷款年限 "repaymentTypeText": "等额本息" // 还款方式文本 } // 更多记录... ] }}
3.3 获取历史记录详情 API
URL: /v1/history/detail/{recordId}
方法: GET
请求头: Authorization: Bearer {token}
响应数据: 与贷款计算API的响应数据相同
3.4 删除历史记录 API
URL: /v1/history/delete/{recordId}
方法: DELETE
请求头: Authorization: Bearer {token}
响应数据:
{ "code": 0, "msg": "删除成功", "data": null}
3.5 清空历史记录 API
URL: /v1/history/clear
方法: DELETE
请求头: Authorization: Bearer {token}
响应数据:
{ "code": 0, "msg": "清空成功", "data": null}
4. 对比相关接口
4.1 创建贷款对比 API
URL: /v1/comparison/create
方法: POST
请求头: Authorization: Bearer {token}
请求参数:
{ "record1Id": 1, // 第一条记录ID "record2Id": 2 // 第二条记录ID}
响应数据:
{ "code": 0, "msg": "创建成功", "data": { "comparisonId": 1 // 对比记录ID }}
4.2 获取对比结果 API
URL: /v1/comparison/detail/{comparisonId}
方法: GET
请求头: Authorization: Bearer {token}
响应数据:
{ "code": 0, "msg": "获取成功", "data": { "record1": { // 第一条记录的详细信息，与历史记录详情相同 }, "record2": { // 第二条记录的详细信息，与历史记录详情相同 }, "equalCompare": { // 等额本息对比结果 "monthlyPaymentDiff": 1000, // 月供差额(元) "totalRepaymentDiff": 240000, // 还款总额差额(元) "totalInterestDiff": 240000 // 总利息差额(元) }, "principalCompare": { // 等额本金对比结果 "firstMonthPaymentDiff": 1500, // 首月还款差额(元) "decreasePerMonthDiff": 5, // 每月递减差额(元) "totalRepaymentDiff": 200000, // 还款总额差额(元) "totalInterestDiff": 200000 // 总利息差额(元) }, "conclusion": "在等额本息还款方式下，方案一比方案二少付利息240000元，月供也低1000元。在等额本金还款方式下，方案一比方案二少付利息200000元，首月还款也低1500元。" // 对比结论 }}
API 使用说明
身份认证
除了登录接口和获取默认利率选项接口外，其他所有接口都需要在请求头中携带身份认证token：
Authorization: Bearer {token}
其中，{token} 是用户登录成功后返回的身份认证令牌。
请求方式
GET 请求：参数通过 URL 查询字符串传递
POST/PUT/DELETE 请求：参数通过 JSON 格式的请求体传递
数据格式约定
贷款金额单位为万元，前端显示和后端存储均保持一致
利率以百分比形式存储，如4.5表示4.5%
计算结果金额单位为元，保留2位小数
历史记录按创建时间倒序排列
用户只能查看和操作自己的历史记录
