OneManager.js API 文档

完整的 API 参考指南，包含 OneManager、OneStorage 和 OneStorageSync 的使用方法

简介

OneManager.js 是一个前端 API 客户端库，提供了与后端服务通信的便捷方式，并封装了类似 localStorage 的存储 API，支持异步和同步两种模式。

1. OneManager 类

主要的 API 客户端类，用于与后端服务通信。

构造函数

new OneManager(baseUrl, appKey = '')

参数：

  • baseUrl：后端服务的基础 URL
  • appKey：可选，API 密钥，用于身份验证

示例：

const oneManager = new OneManager('http://localhost:3000', 'demo-diary-key-789');

方法

setAppKey(appKey)

设置 API 密钥

参数：

  • appKey：API 密钥

返回值：

  • OneManager 实例，支持链式调用

示例：

oneManager.setAppKey('new-api-key');

async request(endpoint, options = {})

通用请求方法，用于发送 HTTP 请求到后端服务

参数：

  • endpoint：API 端点路径，例如 /health
  • options：可选，请求配置对象，包括：
    • method：HTTP 方法，默认为 GET
    • headers：请求头对象
    • body：请求体数据，对象会自动转换为 JSON 字符串

返回值：

  • Promise，解析为响应数据

示例：

const response = await oneManager.request('/health', { method: 'GET' });

async healthCheck()

健康检查

返回值：

  • Promise，解析为健康检查结果

示例：

const healthStatus = await oneManager.healthCheck();

async register(username, password, birthday)

用户注册

参数：

  • username：用户名
  • password：密码
  • birthday：生日，格式为 YYYY-MM-DD

返回值：

  • Promise，解析为注册结果

示例：

const result = await oneManager.register('testuser', 'password123', '1990-01-01');

async login(username, password)

用户登录

参数：

  • username：用户名
  • password：密码

返回值：

  • Promise，解析为登录结果

示例：

const result = await oneManager.login('testuser', 'password123');

async resetPassword(username, birthday, newPassword)

重置密码

参数：

  • username：用户名
  • birthday：生日，格式为 YYYY-MM-DD
  • newPassword：新密码

返回值：

  • Promise，解析为重置密码结果

示例：

const result = await oneManager.resetPassword('testuser', '1990-01-01', 'newpassword123');

async createOrUpdateUser(userData)

创建或更新用户

参数：

  • userData：用户数据对象

返回值：

  • Promise，解析为操作结果

示例：

const result = await oneManager.createOrUpdateUser({ externalUserId: 'testuser' });

async getUserByExternalId(externalUserId)

根据外部用户 ID 获取用户信息

参数：

  • externalUserId：外部用户 ID

返回值：

  • Promise，解析为用户信息

示例：

const userInfo = await oneManager.getUserByExternalId('testuser');

async getUserById(userId)

根据内部用户 ID 获取用户信息

参数：

  • userId：内部用户 ID

返回值：

  • Promise，解析为用户信息

示例：

const userInfo = await oneManager.getUserById('123456');

async updateBasicInfo(userId, basicInfo)

更新用户基础信息

参数：

  • userId：内部用户 ID
  • basicInfo：基础信息对象

返回值：

  • Promise，解析为更新结果

示例：

const result = await oneManager.updateBasicInfo('123456', { nickname: '测试用户' });

async updatePermission(userId, permissionInfo)

更新用户权限信息

参数：

  • userId：内部用户 ID
  • permissionInfo：权限信息对象

返回值：

  • Promise，解析为更新结果

示例：

const result = await oneManager.updatePermission('123456', { role: 'admin' });

async getExtraSmall(userId)

获取用户的 extraSmall 存储数据

参数：

  • userId：内部用户 ID

返回值：

  • Promise，解析为存储数据

示例：

const data = await oneManager.getExtraSmall('123456');

async updateExtraSmall(userId, jsonData)

更新用户的 extraSmall 存储数据

参数：

  • userId：内部用户 ID
  • jsonData：要存储的数据，可以是对象或 JSON 字符串

返回值：

  • Promise，解析为更新结果

示例：

const result = await oneManager.updateExtraSmall('123456', { key: 'value' });

async getExtraMedium(userId)

获取用户的 extraMedium 存储数据

参数：

  • userId：内部用户 ID

返回值：

  • Promise，解析为存储数据

示例：

const data = await oneManager.getExtraMedium('123456');

async updateExtraMedium(userId, jsonData)

更新用户的 extraMedium 存储数据

参数：

  • userId：内部用户 ID
  • jsonData：要存储的数据，可以是对象或 JSON 字符串

返回值：

  • Promise，解析为更新结果

示例：

const result = await oneManager.updateExtraMedium('123456', { key: 'value' });

async getExtraLarge(userId)

获取用户的 extraLarge 存储数据

参数：

  • userId：内部用户 ID

返回值：

  • Promise，解析为存储数据

示例：

const data = await oneManager.getExtraLarge('123456');

async updateExtraLarge(userId, jsonData)

更新用户的 extraLarge 存储数据

参数：

  • userId：内部用户 ID
  • jsonData：要存储的数据，可以是对象或 JSON 字符串

返回值：

  • Promise，解析为更新结果

示例：

const result = await oneManager.updateExtraLarge('123456', { key: 'value' });

async deleteUser(userId)

删除用户

参数：

  • userId：内部用户 ID

返回值：

  • Promise，解析为删除结果

示例：

const result = await oneManager.deleteUser('123456');

saveLoginInfo(username, password)

保存登录信息到本地存储

参数：

  • username：用户名
  • password：密码

示例：

oneManager.saveLoginInfo('testuser', 'password123');

loadLoginInfo()

从本地存储加载登录信息

返回值：

  • 登录信息对象 { username, password }，如果不存在则返回 null

示例：

const loginInfo = oneManager.loadLoginInfo();

removeLoginInfo()

从本地存储移除登录信息

示例：

oneManager.removeLoginInfo();

async autoLogin()

自动登录，使用本地存储的登录信息

返回值：

  • Promise，解析为登录结果对象 { success, username, result, error }

示例：

const autoLoginResult = await oneManager.autoLogin();
if (autoLoginResult.success) {
    console.log('自动登录成功');
}

2. OneStorage 类

封装 OneManager，提供类似 localStorage 的异步 API。

构造函数

new OneStorage(oneManager, externalUserId, storageType = 'extraSmall')

参数：

  • oneManager：OneManager 实例
  • externalUserId：外部用户 ID
  • storageType：存储类型，可选值为 extraSmall、extraMedium、extraLarge，默认为 extraSmall

示例：

const storage = new OneStorage(oneManager, 'testuser', 'extraSmall');

方法

async load()

从服务器加载数据

返回值：

  • Promise，解析为加载的数据

示例：

await storage.load();

async getItem(key)

获取指定键的值

参数：

  • key：要获取的键名

返回值：

  • Promise，解析为对应的值，如果键不存在则返回 null

示例：

const value = await storage.getItem('diaries');

async setItem(key, value)

设置指定键的值

参数：

  • key：要设置的键名
  • value：要设置的值

返回值：

  • Promise，解析为操作结果

示例：

await storage.setItem('diaries', [{ title: '日记1', content: '内容1' }]);

async removeItem(key)

移除指定键

参数：

  • key：要移除的键名

返回值：

  • Promise，解析为操作结果

示例：

await storage.removeItem('diaries');

async clear()

清空所有数据

返回值：

  • Promise，解析为操作结果

示例：

await storage.clear();

async keys()

获取所有键

返回值：

  • Promise，解析为键名数组

示例：

const keys = await storage.keys();

async length()

获取数据数量

返回值：

  • Promise，解析为数据数量

示例：

const length = await storage.length();

async key(index)

获取指定索引的键

参数：

  • index：索引值

返回值：

  • Promise，解析为对应索引的键名，如果索引超出范围则返回 null

示例：

const key = await storage.key(0);

3. OneStorageSync 类

封装 OneManager，提供类似 localStorage 的同步 API，带有延迟保存机制。

构造函数

new OneStorageSync(oneManager, externalUserId, storageType = 'extraSmall')

参数：

  • oneManager：OneManager 实例
  • externalUserId：外部用户 ID
  • storageType：存储类型，可选值为 extraSmall、extraMedium、extraLarge，默认为 extraSmall

示例：

const storage = new OneStorageSync(oneManager, 'testuser', 'extraSmall');

属性

onSaveError

保存错误回调函数，当自动保存失败时调用

示例：

storage.onSaveError = function(error) {
    console.error('自动保存失败:', error);
    alert('自动保存失败，请手动点击保存按钮重试！');
};

方法

async load()

从服务器加载数据

返回值：

  • Promise，解析为加载的数据

示例：

await storage.load();

getItem(key)

获取指定键的值（同步）

参数：

  • key：要获取的键名

返回值：

  • 对应的值，如果键不存在则返回 null

示例：

const value = storage.getItem('diaries');

setItem(key, value)

设置指定键的值（同步）

参数：

  • key：要设置的键名
  • value：要设置的值

示例：

storage.setItem('diaries', [{ title: '日记1', content: '内容1' }]);

removeItem(key)

移除指定键（同步）

参数：

  • key：要移除的键名

示例：

storage.removeItem('diaries');

clear()

清空所有数据（同步）

示例：

storage.clear();

keys()

获取所有键（同步）

返回值：

  • 键名数组

示例：

const keys = storage.keys();

length()

获取数据数量（同步）

返回值：

  • 数据数量

示例：

const length = storage.length();

key(index)

获取指定索引的键（同步）

参数：

  • index：索引值

返回值：

  • 对应索引的键名，如果索引超出范围则返回 null

示例：

const key = storage.key(0);

async saveImmediately()

强制立即保存数据到服务器（异步）

返回值：

  • Promise，解析为保存结果

示例：

await storage.saveImmediately();

destroy()

销毁实例，清理资源

示例：

storage.destroy();

完整使用示例

以下是基于 demo-diary.html 的完整使用示例：

// 初始化 OneManager
const oneManager = new OneManager('http://localhost:3000', 'demo-diary-key-789');

// 尝试自动登录
const autoLoginResult = await oneManager.autoLogin();
if (autoLoginResult.success) {
    // 登录成功，初始化应用
    initApp(autoLoginResult.username);
} else {
    // 显示登录界面
    showLogin();
}

// 初始化应用
async function initApp(externalUserId) {
    // 创建 OneStorageSync 实例
    const storage = new OneStorageSync(oneManager, externalUserId);
    
    // 添加保存错误处理回调
    storage.onSaveError = function(error) {
        console.error('自动保存失败:', error);
        alert('自动保存失败，请手动点击保存按钮重试！');
    };
    
    // 加载数据
    await storage.load();
    
    // 获取日记数据
    const diaries = storage.getItem('diaries') || [];
}

// 创建新日记
function createNewDiary() {
    const newDiary = {
        id: Date.now().toString(),
        title: '',
        content: '',
        date: new Date().toISOString(),
        color: '#ffffff'
    };
    
    diaries.push(newDiary);
    storage.setItem('diaries', diaries);
    // ...
}

// 保存日记
async function saveDiary() {
    storage.setItem('diaries', diaries);
    await storage.saveImmediately();
}

存储类型说明

存储类型 容量限制 适用场景
extraSmall 小容量 适合存储少量数据，如配置信息、简短列表等
extraMedium 中等容量 适合存储中等大小的数据，如日记列表、用户偏好设置等
extraLarge 大容量 适合存储大量数据，如完整的日记内容、多媒体数据等

注意事项

  1. 在使用 OneStorage 或 OneStorageSync 之前，必须先调用 load() 方法加载数据
  2. OneStorageSync 提供的同步 API 仅在内存中操作，实际保存到服务器是异步的
  3. OneStorageSync 会自动延迟保存数据，以优化性能，也可以通过 saveImmediately() 方法强制立即保存
  4. 所有 API 调用都可能抛出错误，建议使用 try-catch 进行错误处理
  5. 在不再使用 OneStorageSync 实例时，建议调用 destroy() 方法清理资源