Lucky框架中数组参数路由构建问题的分析与解决方案

问题背景

在Lucky框架中开发API时，开发者可能会遇到一个特殊场景：当Action中定义了数组类型的参数时，使用路由构建器生成的URL会出现参数编码问题。具体表现为数组参数被整体编码为一个字符串，而非预期的多个独立参数。

问题重现

考虑以下典型场景：

class Reports::Query < ApiAction
  param codes : Array(String)

  get "/reports/query" do
    results = ReportQuery.new.codes(codes)
    json(ReportSerializer.for_collection(results))
  end
end

当开发者尝试使用with方法构建路由时：

client.exec(Reports::Query.with(codes: ["a", "b", "c"]))

实际生成的URL会将整个数组编码为单个字符串：

/reports/query?codes=%5B%22a%22%2C+%22b%22%2C+%22c%22%5D

这导致服务器端接收到的参数格式不正确，最终返回400错误。

问题本质

这个问题源于Lucky框架的路由构建器对数组参数的处理方式。默认情况下，它直接将整个数组对象进行URL编码，而不是按照Web标准将数组展开为多个同名参数。

解决方案

临时解决方案

在等待官方修复期间，可以采用手动构建URL参数的方式：

params = URI::Params.encode({"codes[]": ["a", "b"]})
response = client.get("#{Reports::Query.url_without_query_params}?#{params}")

这种方法显式地使用了codes[]的命名约定，这是许多Web框架(如Rails)处理数组参数的标准方式。

长期解决方案

从框架设计角度，Lucky应该改进其路由构建器，使其能够：

1. 自动检测参数是否为数组类型
2. 对数组参数采用param[]=value1&param[]=value2的标准格式
3. 保持向后兼容性

最佳实践建议

1. 对于简单的API测试，优先考虑使用POST请求发送JSON body
2. 在必须使用GET请求时，考虑将数组参数转换为逗号分隔的字符串
3. 保持API文档与实现的一致性，明确参数格式要求

总结

这个问题虽然看似简单，但它触及了Web开发中参数序列化的核心概念。理解这个问题有助于开发者更深入地掌握HTTP协议和Web框架的工作原理。在Lucky框架官方修复之前，采用手动参数编码的方式是一个可靠的临时解决方案。