ESP32上Alpaca服务器API请求404错误排查求助

1. 核对Microdot V2的路由语法变化 #

Microdot V1与V2的路由参数占位符语法完全不同：

• V1使用<param>格式，V2要求替换为{param}
• 检查src/alpacadevice.py中telescope相关路由，比如原V1的/api/v1/telescope/<device_num>/connected是否改为V2要求的/api/v1/telescope/{device_num}/connected

2. 确认路由是否成功注册 #

• 在服务器启动前，打印所有已注册路由，验证目标端点是否存在：

  for route in app.routes:
      print(f"已注册路由: {route.methods} {route.path}")
  

  如果输出中没有GET /api/v1/telescope/{device_num}/connected和PUT /api/v1/telescope/{device_num}/connected，说明路由注册逻辑存在问题，比如望远镜设备的路由未被正确挂载到主应用

3. 检查子路由挂载方式 #

MiPyAlpaca原代码可能使用子应用/蓝图拆分路由，Microdot V2的子应用挂载逻辑与V1不同：

• 确认原V1的app.mount('/api/v1', telescope_app)这类代码是否已适配V2的API，比如改为app.add_url_rule('/api/v1/<path:path>', view_func=telescope_app)或使用V2官方文档中的子路由挂载方式

4. 验证路由参数传递逻辑 #

• 检查connected端点的处理函数是否正确接收device_num参数，Microdot V2要求函数参数名与路由占位符完全一致：

  @app.route('/api/v1/telescope/{device_num}/connected', methods=['GET', 'PUT'])
  def handle_connected(request, device_num):
      # 业务逻辑代码
  

  若参数名不匹配或未声明参数，会导致路由无法正确匹配

5. 检查路径的精确匹配性 #

• ASCOM Alpaca API要求路径严格区分大小写，确认请求路径/api/v1/telescope/0/connected与代码中路由的大小写完全一致
• Microdot V2默认精确匹配路径，检查代码中路由是否存在末尾多余斜杠（如/api/v1/telescope/{device_num}/connected/），导致请求路径不匹配

6. 排查中间件与错误处理的干扰 #

• 确认迁移保留的错误处理模块是否兼容Microdot V2，比如自定义404处理是否提前拦截了正常路由的匹配
• 临时禁用自定义错误处理和中间件，测试端点是否能正常响应

内容的提问来源于stack exchange，提问作者Brocas Sylvain