Apex REST — Annotations & Methods

好，同学们，咱们今天来聊聊 Apex REST 这块儿，它怎么让你自己写的 Apex 类变成一个 RESTful 的 Web 服务。听起来有点陌生？没关系，我一步一步给你讲透。 首先，你想让外部系统能通过 HTTP 调到你 Salesforce 里的代码，你就得在类上面加一个注解，叫 `@RestResource`。这个注解得放在类的第一行，里面还要配一个 `urlMapping`，比如 `'/myService/*'`，这意思就是：外面的人访问 “你的实例名/services/apexrest/myService/...” 这个路径时，请求就会被交给你这个类来处理。注意哦，类名可以随便起，但映射的路径是你自己定义的。 然后，类里面你要写方法，不同 HTTP 动词对应不同的处理逻辑。怎么做呢？很简单，在每个方法头上再分别加上对应的注解： - 查数据用 `@HttpGet` - 新增数据用 `@HttpPost` - 更新数据用 `@HttpPut` - 删除数据用 `@HttpDelete` - 部分更新用 `@HttpPatch` 这几个注解就是告诉 Salesforce：当外面用 GET 请求过来，就找带 `@HttpGet` 的方法；POST 请求找 `@HttpPost` 的，以此类推。 注意，这里面有几条硬规矩你必须遵守： - 所有这些方法必须声明成 `global static`，也就是全局静态的。因为平台要直接调用它们，没有实例化这一步。 - 对于 `@HttpGet` 和 `@HttpDelete` 方法，它们不能接收任何参数，参数是通过 URL 里带过来的，我们一般用 `RestContext.request.params` 去取。 - 那 POST、PUT、PATCH 这些方法，想拿到请求体里的数据怎么办？你可以在方法里定义参数，参数名要跟请求体里的 JSON 字段名对上，Salesforce 会自动把请求体反序列化给你填进去。如果你不定义参数，也可以通过 `RestContext.request.requestBody` 拿到原始 Blob，自己解析。 说到格式，Apex REST 默认用 JSON，外面发来的 JSON 会自动映射到你的 Apex 对象，你返回的 Apex 对象也会自动变成 JSON 响应体。但是有一点你得留神：返回对象的时候，只有公开的、被标注为 `webservice` 的成员变量才会被序列化到响应里，私有的、受保护的统统不会出现。所以如果你想某个字段暴露出去，记得把它声明成 `global` 或 `public`。 有个小坑提醒一下：XML 格式你也能用，但它对集合（列表、集合等）的支持不太好，限制比较多，所以咱们一般都推荐用 JSON 就对了。 另外，如果你的类是在一个托管包里，那 URL 映射就会自动带上包命名空间，比如 “/包命名空间/myService/*”，这个是为了避免不同的包路径冲突，你调用的时候注意路径里多了一层。 好，总结一下：类上加 `@RestResource` 配好路径，方法上贴对应动词注解，方法都 global static，GET/DELETE 不带参数，POST/PUT/PATCH 可以用参数接收请求体，返回值自动变 JSON，私有字段不会暴露。是不是一下子清晰了？有疑问咱们随时停下来讨论。