从零构建符合skill开发规范的技能服务：新手避坑指南

6次阅读

共计 2109 个字符，预计需要花费 6 分钟才能阅读完成。

去年参与某智能音箱技能审核时，遇到一个典型反面教材：某天气查询技能因未遵循基础规范，导致上线三天后被迫下架。其问题包括：

接口随意设计：同一个天气查询功能出现 /getWeather、/query_weather、/weather 三个端点
响应格式混乱：成功时返回{data: {}}，错误时变成{err: {}, msg: ''}
无防护措施：被恶意用户每秒请求上千次导致服务瘫痪

资源型操作（CRUD 为主）
需要缓存优化的场景
开发团队熟悉 HTTP 语义

Python 示例（Flask）：

@app.route('/api/v1/weather', methods=['GET'])
def get_weather():
    """
    规范要素：- 版本号 (v1) 前置
    - 名词复数形式
    - GET 表示查询操作
    """return jsonify({'data': {}}), 200

Node.js 示例（Express）：

app.get('/api/v1/weather', (req, res) => {
  // 统一错误码格式
  res.status(200).json({ 
    code: 200,
    data: {}})
})

复杂关联数据查询
移动端需要字段裁剪
频繁的 API 演进需求

skill-service/
├── docs/               # 文档目录
│   └── api-spec.yaml   # Swagger 文件
├── src/
│   ├── core/           # 核心逻辑
│   ├── models/         # 数据模型
│   ├── utils/          # 工具类
│   └── app.py          # 主入口
├── tests/              # 测试代码
├── .env                # 环境配置
└── requirements.txt    # Python 依赖

Python 错误处理：

{
  "code": 400102,  # 业务错误码
  "message": "城市参数缺失",
  "detail": {
    "field": "city",
    "type": "required"
  }
}

Node.js 成功响应：

{
  "request_id": "abcd1234",  // 请求追踪 ID
  "timestamp": 1620000000,
  "data": {
    "temperature": 26,
    "weather": "晴"
  }
}

from flasgger import Swagger

app.config['SWAGGER'] = {
    "title": "天气技能 API",
    "version": "1.0",
    "headers": ["X-Request-ID"],
    "specs_route": "/api-docs/"
}
Swagger(app)

Node.js 令牌桶算法：

const rateLimit = require('express-rate-limit')

const limiter = rateLimit({
  windowMs: 15 * 60 * 1000, // 15 分钟
  max: 100, // 每个 IP 限制
  standardHeaders: true,
  legacyHeaders: false,
})

app.use('/api/', limiter)

本地缓存：适合配置类数据（如城市列表）
Redis 缓存：适合会话级数据（如用户偏好）
CDN 缓存：适合静态资源（如天气图标）

Python 内存缓存示例：

from functools import lru_cache

@lru_cache(maxsize=128)
def get_city_code(city_name):
    # 数据库查询操作
    return db.query(...)

sequenceDiagram
    用户 ->>+ 技能服务: 发起登录
    技能服务 ->>+ 认证服务器: 跳转授权页
    认证服务器 -->>- 用户: 输入账号密码
    认证服务器 ->>+ 技能服务: 返回 code
    技能服务 ->> 认证服务器: 用 code 换 token
    认证服务器 -->>- 技能服务: 返回 access_token

Python AES 加密示例：

from cryptography.fernet import Fernet

key = Fernet.generate_key()  # 保存到安全位置
cipher = Fernet(key)
encrypted = cipher.encrypt(b"user_secret")
decrypted = cipher.decrypt(encrypted)