全球化团队用工正在成为常态，Oyster HR 这类平台把跨国雇佣、薪酬发放与合规文件处理抽象成了标准 API。在 Vue 3 项目中接入这类系统，难点并不在于调通某个接口，而是如何让分散在十几个国家的员工数据在前端保持一致性，并且让后续拓展新雇佣地区时不引发大面积重构。本文围绕工程化落地思路，拆解从构建配置到状态管理的完整方案。
请求层与构建链的工程化封装
在 Vite 驱动的 Vue 3 工程中，直接在各业务组件里用 fetch 调用 Oyster HR 接口会导致令牌管理混乱。更合理的做法是建立独立的 oysterClient 模块，在 vite.config.js 中通过环境变量注入基础地址与客户端密钥，构建时完成替换。这样开发、测试与生产环境切换不需要改业务代码，也避免密钥硬编码进仓库。
下面示例展示了一个最小可用的封装，它在请求头注入 Bearer 令牌，并对响应做统一拆包。注意所有尖括号在代码示例内都已转义，保证粘贴到文章系统不会破坏结构。
import axios from 'axios';
const baseURL = import.meta.env.VITE_OYSTER_BASE;
const token = import.meta.env.VITE_OYSTER_TOKEN;
export const oysterClient = axios.create({
baseURL: baseURL,
headers: {
Authorization: 'Bearer ' + token,
'Content-Type': 'application/json'
}
});
oysterClient.interceptors.response.use(
function (resp) {
return resp.data;
},
function (err) {
if (err.response && err.response.status === 401) {
console.warn('Oyster HR 令牌失效，需要刷新');
}
return Promise.reject(err);
}
);
这种封装带来的好处是，当 Oyster HR 升级鉴权方式时，只需修改 oysterClient 一处。业务组件永远只关心返回的纯数据，不必处理通用的错误分支。配合 Vite 的按需编译，该模块只在真正调用人事相关页面时才被打进分包，控制主包体积。
用 Pinia 统一多国员工数据状态
Oyster HR 返回的员工对象带有国家代码、本地货币与多语言姓名等字段。如果各个组件各自拉取并缓存，会出现同一员工在薪酬页显示美元、在信息页显示欧元的冲突。使用 Pinia 建立全局 employeeStore，可以把跨国员工列表、按国家分组的合规状态收敛到单一数据源。
下面代码演示了 store 中如何按雇佣国建立索引，并暴露 getters 给组件使用。这样在 Vue 模板里无需重复计算，也能保证任意页面读取到的员工数据都是同一份引用。
import { defineStore } from 'pinia';
export const useEmployeeStore = defineStore('employee', {
state: () => ({
list: [],
byCountry: {}
}),
actions: {
async loadFromOyster() {
const data = await oysterClient.get('/v1/employees');
this.list = data;
this.byCountry = data.reduce((acc, item) => {
const key = item.country_code;
if (!acc[key]) acc[key] = [];
acc[key].push(item);
return acc;
}, {});
}
},
getters: {
euEmployees: (state) => state.list.filter(e => e.region === 'EU')
}
});
在实际项目中，我们还会把合规文档状态单独拆出，因为不同国家对劳动合同附件的要求差异极大。Pinia 的模块化让这部分可以独立测试，比如模拟法国员工缺少 URSSAF 证明时，界面应给出本地化提示。工程化价值体现在：当 Oyster HR 新增一个中东雇佣国，只需在 byCountry 逻辑里追加映射，组件层几乎零改动。
配置驱动的地区接入与表单校验前置
传统做法每接一个新国家就复制一份页面，最终导致 Vue 路由表里堆满 FranceView、JapanView。工程化方案是把地区差异抽成 JSON 配置，前端根据 Oyster HR 返回的受雇国列表动态渲染表单。如下配置描述了两个国家的必填字段与币种，业务组件读取后生成对应 <input> 元素。
{
"FR": {
"currency": "EUR",
"required_fields": ["national_id", "urssaf_proof"],
"locale": "fr-FR"
},
"JP": {
"currency": "JPY",
"required_fields": ["my_number", "residence_card"],
"locale": "ja-JP"
}
}
表单校验因此可以从后端响应失败提前到用户输入阶段。我们在 Vue 3 的 setup 中读取配置，结合 Oyster HR 的字段规则生成校验函数，用户漏填日本居留卡时立刻看到提示，而不是等提交后收到 422 错误。这种前置不仅减少网络往返，也显著降低跨国员工的填报挫败感。
最后，组件本身通过 defineAsyncComponent 懒加载，地区配置变更不涉及路由重写。整体来看，Vue 3 的工程化并不是堆砌工具，而是用清晰的边界把 Oyster HR 的全球差异隔离在配置与请求层，让业务开发者专注交互而非合规细节。