POST请求Payload构建最佳实践及代码优化咨询

问题描述 #

我正在构建POST请求的Payload，当前代码结构冗余不够简洁，想咨询两个问题：

1. 是否需要为该Payload单独定义Type？
2. 针对documents对象数组，有没有更高效的数据提取方式？

当前Payload代码如下：

const payload = {
      empCode: userId,
      name: firstName,
      doj: moment(employee?.doj?.date).format('DD MMM, YYYY'),
      designation: designation ?? '',
      location: resForms.countryOfBirth ?? '',
      region: resForms.region ?? '',
      email: email ?? '',
      contact: employee?.profile?.contact,
      rmMail: employee?.profile?.rmMail,
      hr: hr ?? '',
      Aadhar_Card: resForms.aadharNumber ?? '',
      Latest_Electricity_Bill: documents['uploadLatestElectricityBill']?.[0]['signedUrl'] ?? '',
      Highest_Degree_Certificates: documents['uploadDegreeCertificate']?.[0]['signedUrl'] ?? '',
      '10th_Marksheet':
        documents['educationDetails']?.[0]?.['uploadDegreeMarksheet'][0]['signedUrl'] ?? '',
      '12th_Marksheet':
        documents['educationDetails']?.[1]?.['uploadDegreeMarksheet'][0]['signedUrl'] ?? '',
      Bachelors_Marksheet:
        documents['educationDetails']?.[2]?.['uploadDegreeMarksheet'][0]['signedUrl'] ?? '',
      Relieving_Letter: documents['uploadRelievingLetter']?.[0]['signedUrl'] ?? '',
      Last_Three_Month_Salary_Slip: documents['uploadLastMonthsPayslips']?.[0]['signedUrl'] ?? '',
      PED_Form: documents['uploadPedForm']?.[0]['signedUrl'] ?? ''
    };

问题解答 #

1. 是否需要为Payload单独定义Type？ #

非常建议定义，核心价值如下：

• 提前错误检测：无论是TypeScript类型还是JSDoc注释，都能在开发阶段发现字段类型不匹配、必填字段缺失等问题，避免运行时报错。
• 提升开发效率：编辑器会提供字段自动补全和类型提示，减少手动拼写错误。
• 增强可读性：明确的类型定义能让后续维护者快速理解Payload的结构、字段含义和可选性。
• 保证一致性：避免不同场景下构造同类型Payload时出现结构差异。

示例实现

TypeScript类型定义：

interface EmployeePayload {
  empCode: string | number;
  name: string;
  doj: string;
  designation: string;
  location: string;
  region: string;
  email: string;
  contact?: string;
  rmMail?: string;
  hr: string;
  Aadhar_Card: string;
  Latest_Electricity_Bill: string;
  Highest_Degree_Certificates: string;
  '10th_Marksheet': string;
  '12th_Marksheet': string;
  Bachelors_Marksheet: string;
  Relieving_Letter: string;
  Last_Three_Month_Salary_Slip: string;
  PED_Form: string;
}

// 使用时直接指定类型
const payload: EmployeePayload = { /* ... */ };

JavaScript JSDoc注释：

/**
 * @typedef {Object} EmployeePayload
 * @property {string|number} empCode
 * @property {string} name
 * @property {string} doj
 * @property {string} designation
 * @property {string} location
 * @property {string} region
 * @property {string} email
 * @property {string} [contact]
 * @property {string} [rmMail]
 * @property {string} hr
 * @property {string} Aadhar_Card
 * @property {string} Latest_Electricity_Bill
 * @property {string} Highest_Degree_Certificates
 * @property {string} 10th_Marksheet
 * @property {string} 12th_Marksheet
 * @property {string} Bachelors_Marksheet
 * @property {string} Relieving_Letter
 * @property {string} Last_Three_Month_Salary_Slip
 * @property {string} PED_Form
 */

/** @type {EmployeePayload} */
const payload = { /* ... */ };

2. 优化documents对象的数据提取 #

当前代码重复了大量?.[0]['signedUrl'] ?? ''的逻辑，可通过映射表+工具函数简化：

步骤1：定义字段映射关系

把Payload文档字段与documents中的键、索引做对应：

const documentMappings = [
  { payloadKey: 'Latest_Electricity_Bill', docKey: 'uploadLatestElectricityBill' },
  { payloadKey: 'Highest_Degree_Certificates', docKey: 'uploadDegreeCertificate' },
  { payloadKey: '10th_Marksheet', docKey: 'educationDetails', index: 0 },
  { payloadKey: '12th_Marksheet', docKey: 'educationDetails', index: 1 },
  { payloadKey: 'Bachelors_Marksheet', docKey: 'educationDetails', index: 2 },
  { payloadKey: 'Relieving_Letter', docKey: 'uploadRelievingLetter' },
  { payloadKey: 'Last_Three_Month_Salary_Slip', docKey: 'uploadLastMonthsPayslips' },
  { payloadKey: 'PED_Form', docKey: 'uploadPedForm' }
];

步骤2：封装提取工具函数

将重复的提取逻辑封装，降低冗余：

function getDocumentUrl(documents, mapping) {
  if (mapping.index !== undefined) {
    // 处理带索引的educationDetails字段
    return documents[mapping.docKey]?.[mapping.index]?.['uploadDegreeMarksheet']?.[0]?.['signedUrl'] ?? '';
  }
  // 普通文档字段提取
  return documents[mapping.docKey]?.[0]?.['signedUrl'] ?? '';
}

步骤3：批量生成文档字段

通过reduce遍历映射表，生成文档相关的Payload字段：

const documentFields = documentMappings.reduce((acc, mapping) => {
  acc[mapping.payloadKey] = getDocumentUrl(documents, mapping);
  return acc;
}, {});

步骤4：整合最终Payload

将基础字段与批量生成的文档字段合并，代码更简洁：

const payload = {
  empCode: userId,
  name: firstName,
  doj: employee?.doj?.date ? moment(employee.doj.date).format('DD MMM, YYYY') : '',
  designation: designation ?? '',
  location: resForms.countryOfBirth ?? '',
  region: resForms.region ?? '',
  email: email ?? '',
  ...(employee?.profile ?? {}), // 解构profile中的contact、rmMail
  hr: hr ?? '',
  Aadhar_Card: resForms.aadharNumber ?? '',
  ...documentFields // 展开批量生成的文档字段
};

额外优化建议 #

1. 空值处理统一封装：避免重复写?? ''，可封装工具函数：

const withDefault = (value, defaultValue = '') => value ?? defaultValue;

// 使用示例：
designation: withDefault(designation),
location: withDefault(resForms.countryOfBirth),

2. moment空值防护：原代码中若employee?.doj?.date不存在，moment会返回当前时间，建议添加空值判断（如上述整合代码所示）。

内容的提问来源于stack exchange，提问作者Yash