Vue Storefront 中处理自定义 SAP OCC 端点的完整指南-CSDN博客

Vue Storefront 中处理自定义 SAP OCC 端点的完整指南

vue-storefront The open-source frontend for any eCommerce. Built with a PWA and headless approach, using a modern JS stack. We have custom integrations with Magento, commercetools, Shopware and Shopify and total coverage is just a matter of time. The API approach also allows you to merge VSF with any third-party tool like CMS, payment gateways or analytics. Newest updates: https://blog.vuestorefront.io. Always Open Source, MIT license. 项目地址: https://gitcode.com/gh_mirrors/vu/vue-storefront

前言

在 Vue Storefront 项目中与 SAP Commerce Cloud (OCC) 集成时，开发者经常需要处理标准 API 之外的自定义端点。本文将深入探讨两种实现方式：自动生成 API 客户端和手动添加端点支持，帮助开发者根据项目需求选择最佳方案。

方案一：基于 OpenAPI 规范生成 API 客户端（推荐）

为什么这是首选方案？

自动生成 API 客户端是最规范且可维护性最高的方法，特别适合以下场景：

项目中有大量自定义端点需要支持
API 规范相对稳定，不会频繁变更
团队希望保持代码的一致性和标准化

实现原理

通过解析 SAP OCC 提供的 OpenAPI (Swagger) 规范文件，自动生成完整的 TypeScript 客户端代码。这种方式可以：

一次性生成所有端点支持
自动包含类型定义
减少手动编码错误
便于后续更新维护

方案二：手动添加自定义端点支持

适用场景

虽然自动生成是首选方案，但在以下情况下可能需要手动添加：

无法获取 OpenAPI 规范文件
API 正在快速迭代，需要频繁调整
只需要支持少量特殊端点

实现步骤详解

1. 理解 OCC 端点结构

典型的 OCC 端点遵循以下模式：

{baseUrl}/{baseSiteId}/{resource_path}?fields={fields}&lang={language}&curr={currency}

用户相关端点则包含用户ID：

{baseUrl}/{baseSiteId}/user/{userId}/{resource_path}?fields={fields}&lang={language}&curr={currency}

2. 关键参数说明

| 参数 | 来源 | 说明 | |------|------|------| | baseUrl | 环境变量 SAPCC_API_URI | API 基础地址 | | baseSiteId | 中间件配置 | 多站点标识符 | | userId | 请求 Cookie | "current"、"anonymous" 或具体用户ID | | language | 请求 Cookie | 语言标识 | | currency | 请求 Cookie | 货币标识 | | 授权令牌 | 请求 Cookie | 用户认证凭证 |

3. 使用辅助工具方法

Vue Storefront 提供了几个关键工具方法简化开发：

getUserIdFromRequest 自动从请求上下文或参数中提取用户ID，处理了各种边界情况。

createRequestOptions 自动处理以下事项：

添加授权头
设置语言和货币参数
管理不同认证模式

4. 完整实现示例

下面是一个产品兴趣功能的完整实现：

类型定义 (types.ts)

import { BaseProps, BaseUserId, Product } from '@vsf-enterprise/sapcc-types';

export interface GetProductInterestsArgs extends BaseProps, BaseUserId {
  productCode?: string;
}

export interface ProductInterestEntry {
  interestType?: string;
  dateAdded?: string;
  expirationDate?: string;
}

export interface ProductInterestRelation {
  product?: Product;
  productInterestEntry?: Array<ProductInterestEntry>;
}

export interface UserInterestsResponse {
  results: Array<ProductInterestRelation>;
}

端点实现 (custom.ts)

import { 
  createRequestOptions, 
  getUserIdFromRequest, 
  TokenModes 
} from '@vsf-enterprise/sapcc-api';
import { type IntegrationContext } from '../../types';
import type { GetProductInterestsArgs, UserInterestsResponse } from './types';

export async function getProductInterests(
  context: IntegrationContext,
  args: GetProductInterestsArgs
): Promise<UserInterestsResponse> {
  const { config, client } = context;
  
  const userId = getUserIdFromRequest({ context, props: args });
  
  const requestOptions = createRequestOptions({
    context,
    props: args,
    tokenMode: TokenModes.CUSTOMERORAPPLICATION,
  });

  const res = await client.get(
    `/${config.api.baseSiteId}/users/${userId}/productinterests`,
    {
      ...requestOptions,
      params: {
        ...requestOptions.params,
        productCode: args.productCode,
      },
    }
  );

  return res.data;
}

前端调用示例

import { useQuery } from '@tanstack/react-query';
import { useSdk } from '@/sdk/alokai-context';

export function useProductInterests({ productCode }: { productCode: string }) {
  const sdk = useSdk();
  
  return useQuery({
    queryFn: () => 
      sdk.customExtension.getProductInterests({ productCode }),
    queryKey: ['product interests', productCode],
  });
}