Back to Details

clay-upgrade-migration

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Clay Upgrade & Migration

Clay SDK升级与迁移

Overview

概述

Guide for upgrading Clay SDK versions and handling breaking changes.
指导你升级Clay SDK版本并处理破坏性变更。

Prerequisites

前置条件

  • Current Clay SDK installed
  • Git for version control
  • Test suite available
  • Staging environment
  • 已安装当前版本的Clay SDK
  • 用于版本控制的Git
  • 可用的测试套件
  • 预发布（Staging）环境

Instructions

操作步骤

Step 1: Check Current Version

步骤1：查看当前版本

bash
npm list @clay/sdk
npm view @clay/sdk version
bash
npm list @clay/sdk
npm view @clay/sdk version

Step 2: Review Changelog

步骤2：查看更新日志

bash
open https://github.com/clay/sdk/releases
bash
open https://github.com/clay/sdk/releases

Step 3: Create Upgrade Branch

步骤3：创建升级分支

bash
git checkout -b upgrade/clay-sdk-vX.Y.Z
npm install @clay/sdk@latest
npm test
bash
git checkout -b upgrade/clay-sdk-vX.Y.Z
npm install @clay/sdk@latest
npm test

Step 4: Handle Breaking Changes

步骤4：处理破坏性变更

Update import statements, configuration, and method signatures as needed.
根据需要更新导入语句、配置和方法签名。

Output

输出结果

  • Updated SDK version
  • Fixed breaking changes
  • Passing test suite
  • Documented rollback procedure
  • 更新后的SDK版本
  • 已修复的破坏性变更
  • 通过测试套件验证
  • 已记录的回滚流程

Error Handling

错误处理

SDK VersionAPI VersionNode.jsBreaking Changes
3.x2024-0118+Major refactor
2.x2023-0616+Auth changes
1.x2022-0114+Initial release
SDK版本API版本Node.js版本破坏性变更
3.x2024-0118+重大重构
2.x2023-0616+认证方式变更
1.x2022-0114+初始版本

Examples

示例

Import Changes

导入语句变更

typescript
// Before (v1.x)
import { Client } from '@clay/sdk';

// After (v2.x)
import { ClayClient } from '@clay/sdk';
typescript
// Before (v1.x)
import { Client } from '@clay/sdk';

// After (v2.x)
import { ClayClient } from '@clay/sdk';

Configuration Changes

配置变更

typescript
// Before (v1.x)
const client = new Client({ key: 'xxx' });

// After (v2.x)
const client = new ClayClient({
  apiKey: 'xxx',
});
typescript
// Before (v1.x)
const client = new Client({ key: 'xxx' });

// After (v2.x)
const client = new ClayClient({
  apiKey: 'xxx',
});

Rollback Procedure

回滚流程

bash
npm install @clay/sdk@1.x.x --save-exact
bash
npm install @clay/sdk@1.x.x --save-exact

Deprecation Handling

弃用功能处理

typescript
// Monitor for deprecation warnings in development
if (process.env.NODE_ENV === 'development') {
  process.on('warning', (warning) => {
    if (warning.name === 'DeprecationWarning') {
      console.warn('[Clay]', warning.message);
      // Log to tracking system for proactive updates
    }
  });
}

// Common deprecation patterns to watch for:
// - Renamed methods: client.oldMethod() -> client.newMethod()
// - Changed parameters: { key: 'x' } -> { apiKey: 'x' }
// - Removed features: Check release notes before upgrading
typescript
// 在开发环境中监控弃用警告
if (process.env.NODE_ENV === 'development') {
  process.on('warning', (warning) => {
    if (warning.name === 'DeprecationWarning') {
      console.warn('[Clay]', warning.message);
      // 记录到追踪系统以便主动更新
    }
  });
}

// 需要关注的常见弃用模式：
// - 方法重命名：client.oldMethod() -> client.newMethod()
// - 参数变更：{ key: 'x' } -> { apiKey: 'x' }
// - 功能移除：升级前请查看发布说明

Resources

资源

Next Steps

后续步骤

For CI integration during upgrades, see 
clay-ci-integration
.
如需在升级过程中集成CI，请查看
clay-ci-integration
。