Mastra项目中useCompletion示例的问题分析与解决方案

问题背景

在Mastra项目的开发过程中，开发者发现文档中提供的useCompletion示例代码存在功能性问题。该示例在使用过程中无法正常工作，导致API调用失败。具体表现为当调用handleSubmit和complete函数时，系统会始终填充名为prompt的属性，而实际API接口需要的是messages属性。

错误现象

当开发者按照文档示例代码进行操作时，系统会返回错误信息："Argument "messages" is required"。这表明API端点期望接收包含messages属性的请求体，而实际收到的却是包含prompt属性的请求体，导致验证失败。

技术分析

这个问题本质上是一个请求体格式不匹配的问题。Mastra的stream端点设计为接收标准化的消息格式，要求请求中包含messages数组，每个消息对象需要包含role和content属性。而useCompletion的实现则采用了简化的prompt参数方式，直接将用户输入作为prompt属性发送。

这种设计差异导致了接口调用失败。在AI应用开发中，这种格式不匹配的问题很常见，特别是在前后端接口规范不一致的情况下。

解决方案

针对这个问题，开发者提供了一个优雅的中间件解决方案。通过在Mastra实例的中间件层添加请求转换逻辑，可以无缝地将prompt格式转换为messages格式：

export const mastra = new Mastra({
  server: {
    middleware: [
      async (c, next) => {
        if (c.req.method === 'POST' && c.req.path === '/api/agents/completionAgent/stream') {
          const body = await c.req.json();
          if (body && 'prompt' in body) {
            if (!body.messages) {
              body.messages = [{ role: 'user', content: body.prompt }];
            }
            delete body.prompt;
            c.req.json = () => Promise.resolve(body);
          }
        }
        await next();
      },
    ],
  },
});

这个中间件的工作原理是：

1. 拦截特定路径的POST请求
2. 检查请求体中是否包含prompt属性
3. 如果存在prompt但不存在messages，则创建一个标准的messages数组
4. 将prompt内容转换为user角色的消息
5. 删除原始的prompt属性
6. 继续处理请求

最佳实践建议

1. 接口设计一致性：在设计API时，前后端应保持一致的参数命名和结构规范，避免这种转换需求。

2. 文档准确性：示例代码应与实际API要求严格匹配，避免给开发者带来困惑。

3. 中间件使用：当确实需要格式转换时，中间件是一个理想的解决方案，它保持了业务逻辑的纯净性。

4. 类型安全：在TypeScript项目中，可以为请求和响应体定义明确的接口类型，提前发现潜在的类型不匹配问题。

总结

这个问题展示了在实际开发中接口规范不一致带来的挑战，以及如何使用中间件模式优雅地解决这类问题。通过请求转换层，我们可以在不修改核心业务逻辑的情况下适配不同的接口规范，这在集成第三方服务或处理遗留系统时尤为有用。

对于Mastra项目的使用者来说，这个解决方案不仅修复了当前的问题，还提供了一种处理类似接口兼容性问题的参考模式。开发者可以根据实际需求调整中间件的逻辑，例如支持更复杂的消息转换或多轮对话场景。