使用指南
服务管理
创建服务
通过 AnyService 控制台创建服务,需要配置以下基本信息:
基本配置
配置项 | 说明 | 要求 |
---|---|---|
服务名称 | 服务的显示名称 | 便于识别和管理 |
服务标识 | 服务的唯一标识符 | 仅支持英文、数字、下划线,环境内唯一 |
备注 | 服务描述信息 | 可选,用于记录服务用途 |
源站类型 | 后端服务的接入方式 | 公网访问源站 或 腾讯云资源 |
公网访问源站配置
当选择通过公网访问源站时,需要配置:
配置项 | 说明 | 示例 |
---|---|---|
源站协议 | HTTP 或 HTTPS | 默认端口:HTTP(80)、HTTPS(443) |
源站连接信息 | IP 地址或域名 | 139.186.239.126 或 tcb.tencentcloudapi.com:8080 |
腾讯云资源配置
当选择对接腾讯云资源时,需要配置:
配置项 | 说明 | 支持范围 |
---|---|---|
对应资源 | 选择具体的云资源实例 | 上海区的 CVM、CLB、Lighthouse |
端口 | 服务监听端口 | 1-65535 |
安全配置(可选)
配置项 | 说明 | 注意事项 |
---|---|---|
源站访问凭证 | Basic Auth 认证信息 | 遵循 Authorization Basic 规范 |
工作原理:配置后,每次请求会在 Header 中添加 x-anyservice-authorization
字段,源站可用于身份验证或请求来源识别。
⚠️ 安全提示:使用 HTTP 协议时,访问凭证将以明文传输,建议生产环境使用 HTTPS。
管理服务
在服务列表中可以查看和管理已创建的服务:
操作 | 说明 | 注意事项 |
---|---|---|
查看详情 | 查看服务的配置信息和运行状态 | - |
编辑服务 | 修改除标识外的所有配置 | 服务标识不可修改 |
删除服务 | 彻底删除服务及其配置 | 删除前请确保无代码依赖 |
⚠️ 重要提示:服务的修改和删除操作可能影响正在使用该服务的应用,请在操作前谨慎评估影响范围。
服务调用
在小程序中调用
1. 初始化云开发环境
在小程序加载阶段调用一次初始化,全局执行一次即可:
// app.js - 全局初始化
App({
async onLaunch() {
// 初始化云开发环境
wx.cloud.init({
env: "your-env-id" // 替换为您的环境 ID
})
}
})
2. 调用 AnyService 服务
使用 wx.cloud.callContainer
方法调用 AnyService 服务:
// 调用示例
const callAnyService = async () => {
try {
const res = await wx.cloud.callContainer({
path: '/api/users', // 后端 API 路径
method: 'POST', // HTTP 方法
header: {
"X-WX-SERVICE": "tcbanyservice", // 固定值
"X-AnyService-Name": "my-service", // 您的服务标识
"Content-Type": "application/json"
},
data: {
name: '张三',
email: 'zhangsan@example.com'
}
// dataType: 'text' // 可选:不要 SDK 自动解析 JSON 时使用
})
console.log('调用成功:', res.data)
return res.data
} catch (error) {
console.error('调用失败:', error)
throw error
}
}
关键参数说明
参数 | 值 | 说明 |
---|---|---|
X-WX-SERVICE | tcbanyservice | 固定值,标识调用 AnyService |
X-AnyService-Name | 您的服务标识 | 创建服务时设置的标识符 |
path | /api/path | 后端 API 路径,从根目录开始 |
method | GET/POST/PUT/DELETE | HTTP 请求方法 |
dataType | json (默认)/text | 响应数据解析方式 |
错误处理与最佳实践
常见错误处理
const callAnyService = async (path, data = {}) => {
try {
const res = await wx.cloud.callContainer({
path,
method: 'POST',
header: {
"X-WX-SERVICE": "tcbanyservice",
"X-AnyService-Name": "my-service",
"Content-Type": "application/json"
},
data,
timeout: 10000 // 设置超时时间
})
return res.data
} catch (error) {
// 处理不同类型的错误
if (error.errCode === -1) {
console.error('网络请求失败:', error.errMsg)
wx.showToast({ title: '网络连接失败', icon: 'none' })
} else if (error.errCode === 40001) {
console.error('服务未找到:', error.errMsg)
wx.showToast({ title: '服务暂不可用', icon: 'none' })
} else {
console.error('调用失败:', error)
wx.showToast({ title: '请求失败,请重试', icon: 'none' })
}
throw error
}
}
最佳实践建议
- 请求封装:建议将 AnyService 调用封装成通用函数
- 错误处理:为不同错误类型提供相应的用户提示
- 超时设置:为网络请求设置合理的超时时间
- 状态管理:在调用过程中显示加载状态
- 重试机制:对于临时性错误可以实现重试逻辑
📝 提示:其他参数均与 wx.request 保持一致。
请求与响应数据
请求 Header
通过 SDK 调用服务时,系统会自动在 HTTP Header 中携带小程序相关信息,后端可以通过解析这些 Header 获取用户和环境信息:
Header 字段 | 含义 | 说明 |
---|---|---|
X-WX-OPENID | 小程序用户 openid | 用户唯一标识 |
X-WX-APPID | 小程序 AppID | 小程序应用标识 |
X-WX-UNIONID | 小程序用户 unionid | 跨应用用户标识(需满足获取条件) |
X-WX-FROM-OPENID | 资源复用场景下的用户 openid | 资源复用时的原始用户标识 |
X-WX-FROM-APPID | 资源复用场景下的小程序 AppID | 资源复用时的原始应用标识 |
X-WX-FROM-UNIONID | 资源复用场景下的用户 unionid | 资源复用时的原始用户跨应用标识 |
X-WX-ENV | 云环境 ID | 当前调用所在的云开发环境 |
X-WX-SOURCE | 调用来源 | 触发本次调用的来源类型 |
X-WX-PLATFORM | 调用平台 | 发起调用的平台信息 |
X-Forwarded-For | 客户端 IP 地址 | 支持 IPv4 和 IPv6 |
X-AnyService-Name | AnyService 服务标识 | 当前调用的服务标识符 |
响应 Header
AnyService 会在响应中添加以下 Header 字段,用于调试和监控:
Header 字段 | 含义 | 说明 |
---|---|---|
X-Cloudbase-Request-Id | 云开发请求 ID | 用于问题追踪和日志查询 |
X-Cloudbase-Upstream-Status-Code | 源站响应状态码 | 后端服务实际返回的 HTTP 状态码 |
X-Cloudbase-Upstream-Timecost | 源站响应耗时 | 后端服务处理请求的时间(毫秒) |
X-Cloudbase-Upstream-Type | 源站服务类型 | 后端服务的类型标识 |