Grape::Entity::Exposure::WithOptions怎么用？带选项字段暴露详解

在Grape这个Ruby生态里流行的RESTful API框架中，Entity层承担着数据序列化的职责，也就是把模型对象转换成最终输出给客户端的JSON结构。大多数人对expose的基础用法很熟悉，但一旦需要根据条件动态决定字段是否输出、用什么格式输出，就需要借助带选项的暴露机制，也就是Grape::Entity::Exposure::WithOptions所支持的能力。这篇文章会从原理到实践，把这个机制讲透。

一、从普通expose到带选项暴露：机制上的差异

先看最简单的写法。在Entity内部，expose :name会把对象上name方法的返回值原样输出。这种方式简单直接，但缺乏弹性——无论什么场景调用，输出结构都一模一样。

module Entities
  class User < Grape::Entity
    expose :id
    expose :name
    expose :email
  end
end

而带选项的暴露，是在expose调用时传入一组选项参数。框架内部会把这些选项封装进一个WithOptions对象，后续所有的字段定义（包括嵌套的expose块）都会继承并应用这些选项。可以这样理解：WithOptions是一个上下文容器，它把「怎么暴露」的策略和「暴露什么」的字段列表绑定在一起，让序列化行为可以参数化。

查看Grape的源码会发现，每次调用expose时，框架会判断是否传入了选项或代码块。如果有，就构造一个Exposure::WithOptions实例，持有这些选项并代理后续的字段注册。这个设计的妙处在于选项可以层层叠加：外层设置的选项会成为内层暴露的默认值，内层又可以覆盖它。这种继承语义让复杂嵌套结构的控制变得非常简洁。

二、常用选项详解：condition、if、unless与格式化

最常用的选项是条件类选项。condition接受一个Proc，返回truthy时字段才会输出：

module Entities
  class User < Grape::Entity
    expose :id
    expose :name
    # 只有当对象有email时才输出该字段
    expose :email, condition: ->(obj, _opts) { obj.email.present? }
    # 也可以用if/unless，语义更直观
    expose :phone, if: ->(_obj, opts) { opts[:show_phone] }
    expose :internal_note, unless: ->(_obj, opts) { opts[:hide_internal] }
  end
end

注意条件Proc接收两个参数：第一个是被序列化的对象本身，第二个是选项哈希opts。第二个参数是动态控制的关键——调用represent或present时传入的任何参数，都会顺着这个哈希流到每一个条件判断里。比如在API端点中：

get '/users/:id' do
  user = User.find(params[:id])
  present user, with: Entities::User, show_phone: true, hide_internal: true
end

除了条件，格式化也是高频需求。format_with选项允许指定一个格式化器，可以是内置的（如:timestamp），也可以是自定义方法名：

module Entities
  class Article < Grape::Entity
    format_with(:iso_time) { |t| t&.iso8601 }

    expose :created_at, format_with: :iso_time
    expose :price, format_with: ->(v) { format('%.2f', v) }
    expose :summary, as: :abstract do |article, opts|
      article.content.to_s.truncate(opts[:summary_length] || 50)
    end
  end
end

上面同时展示了as选项（重命名输出键）、代码块形式的取值逻辑（不依赖对象上的同名方法）。这些选项可以组合使用，比如既改名又条件输出又格式化，框架会按「先判断条件、再取值、再格式化、最后命名」的顺序处理。

三、嵌套结构与选项继承的实战技巧

当Entity出现嵌套时，WithOptions的选项继承特性就体现出价值了。外层通过块形式设置的选项，会应用到块内所有字段的暴露上，避免重复书写：

module Entities
  class Order < Grape::Entity
    expose :id
    expose :order_no

    # 块内所有字段都只在管理员视角输出
    expose :cost, :supplier, if: ->(_obj, opts) { opts[:admin] } do
      expose :purchase_price, format_with: ->(v) { v.to_f.round(2) }
      expose :supplier_name do |order, _opts|
        order.supplier&.name
      end
    end
  end
end

另一个常见场景是按用户角色裁剪响应。可以在API层把当前用户信息塞进选项，Entity内部据此决定暴露范围：

module Entities
  class Profile < Grape::Entity
    expose :id, :nickname, :avatar_url
    expose :email, if: ->(obj, opts) { opts[:current_user]&.id == obj.id }
    expose :balance, if: ->(_obj, opts) { opts[:current_user]&.admin? }
  end
end

# 端点中统一注入
before do
  @represent_opts = { current_user: current_user }
end

get '/profiles/:id' do
  profile = Profile.find(params[:id])
  present profile, with: Entities::Profile, **@represent_opts
end

这种写法把权限判断从视图层剥离到选项流中，Entity保持纯声明式，测试起来也容易：直接调用Entities::Profile.represent(profile, current_user: user)即可断言输出结构，不需要发起真实HTTP请求。

四、性能与可维护性的注意事项

虽然带选项暴露很灵活，但有几点值得注意。第一，条件Proc在每个字段上都会执行一次，如果一个Entity暴露了几十个条件字段，序列化开销会累积。对于高频接口，建议把强相关的条件合并到块级暴露中，用一次判断覆盖多个字段，减少Proc调用次数。

第二，选项哈希的传递链路要清晰。如果各种魔法参数散落在多个端点里，后期排查「为什么这个字段没输出」会很痛苦。推荐集中定义一份选项常量表，所有端点从这里取值，字段命名的含义一目了然。同时用documentation选项给字段补充说明，配合swagger文档生成，让调用方也能理解字段出现的条件：

expose :secret_key,
  documentation: { type: String, desc: '仅管理员可见，需传入admin选项' },
  if: ->(_obj, opts) { opts[:admin] }

第三，注意safe选项的配合。默认情况下，如果对象上不存在对应的字段方法，序列化会抛异常；加上safe: true后缺失字段会被静默跳过，这在处理异构数据源或可选字段较多的场景中很实用，但也可能掩盖拼写错误，建议只在确实需要的暴露块上局部启用。

总的来说，Grape::Entity::Exposure::WithOptions提供的带选项字段暴露机制，核心价值在于把序列化的「策略」从「数据」中解耦出来。理解选项的继承与传递规则后，你可以用很少的代码实现按角色、按请求动态变化的响应结构，同时保持Entity的声明式风格和可测试性，这正是它在实际项目中相对于手写序列化hash的最大优势。

Grape::EntityWithOptions字段暴露修改时间：2026-09-12 23:24:36