Options
All
  • Public
  • Public/Protected
  • All
Menu

Halo logo

Halo SDK

Project Build npm npm npm version

一个与 Halo api 交互的工具集

English Document

特性

  • 封装认证以简化开发.
  • 异常处理
  • 使用 Halo rest api 更方便
  • 使用 TypeScript 编写,更明确的参数和返回值类型,更好的代码提示

管理后台 API 库

安装

使用 npm 方式安装示例如下:

npm install @halo-dev/admin-api --save

使用示例

以下是一个获取后台文章列表的简单示例:

import { AdminApiClient, HaloRestAPIClient } from "@halo-dev/admin-api";
//halo http 请求客户端.
const haloRestApiClient = new HaloRestAPIClient({
baseUrl: process.env.HALO_BASE_URL,
auth: { adminToken: "halo admin token" },
});
// 通过 haloRestApiCLient 创建 adminApiClient。
const haloAdminClient = new AdminApiClient(haloRestApiClient);
// 获取文章列表
haloAdminClient.post.list().then((res) => {
console.log(res);
});

关于如何通过用户名和密码进行自动认证,这里提供了一个示例 example

由于 @halo-dev/admin-api 依赖 @halo-dev/rest-api-client,而其是基于 axios 进行 http 通信的,因此如果你有需要的话,可以使用 axios, 的拦截器对 halo api 的请求与响应进行一些处理。

import axios from "axios";

// Add a request interceptor
axios.interceptors.request.use(
function (config) {
// Do something before request is sent
return config;
},
function (error) {
// Do something with request error
return Promise.reject(error);
}
);

// Add a response interceptor
axios.interceptors.response.use(
function (response) {
// Any status code that lie within the range of 2xx cause this function to trigger
// Do something with response data
return response;
},
function (error) {
// Any status codes that falls outside the range of 2xx cause this function to trigger
// Do something with response error
return Promise.reject(error);
}
);

@halo-dev/content-api 也可以这样使用拦截器。

前台 API 库

使用 npm 安装示例如下:

npm install @halo-dev/content-api --save

使用示例

同样我们使用一个获取博客前台文章列表的示例如下:

import { ContentApiClient, HaloRestAPIClient } from "@halo-dev/content-api";
// 创建 halo http 请求客户端
const haloRestApiClient = new HaloRestAPIClient({
baseUrl: process.env.HALO_BASE_URL,
auth: { apiToken: process.env.HALO_API_TOKEN },
});
// 通过 http 客户端创建 halo 前台 api 客户端
const haloContentClient = new ContentApiClient(haloRestApiClient);
// 获取文章列表
haloContentClient.post.list().then((res) => {
console.log(res);
});

Halo Rest API Http 通信库

安装

你可以使用 npm 安装它,示例如下:

npm install @halo-dev/rest-api-client

使用 requireimport 导入

// CommonJS
const { HaloRestAPIClient } = require("@halo-dev/rest-api-client");
// ES modules
import { HaloRestAPIClient } from "@halo-dev/rest-api-client";

使用示例

const client = new HaloRestAPIClient({
baseUrl: "https://example.halo.run",
// Use password authentication
auth: {
username: process.env.HALO_USERNAME,
password: process.env.HALO_PASSWORD,
},
});

auth 参数为认证方式,支持以下几种认证方式,示例如下:

  1. 使用 API token 认证,它适用于 halo 博客前台 api 认证
auth: {
apiToken: process.env.HALO_API_TOKEN;
}
  1. 使用 Admin token 认证,它适用于 halo 后台管理 api 认证
auth: {
adminToken: process.env.HALO_ADMIN_TOKEN;
}
  1. 使用自定义请求头认证方式
auth: {
type: "customizeAuth",
authHeader: "Admin-Authorization",
getToken () {
return localStorage.getItem ("Access_Token")
}
}
  1. 使用 OAuth2 Bearer token 的认证方式,最终会在请求头添加 Authorization: bearer some-token
auth: {
oAuthToken: process.env.HALO_OAUTH_TOKEN;
}

Basic 认证

会在请求头添加例如 Authorization: Basic dXNlci1jbGllbi1zZWNyZXQtODg4OA== 这样的 pair

const client = new HaloRestAPIClient({
baseUrl: "https://example.halo.run",
// Use basic authentication
basicAuth: { username: "user", password: "password" },
});

另外还支持通过提供一个 TokenProvider 来接管 halo 的认证,这样不需要在考虑如何实现登录和 token 过期怎么续期的逻辑,示例如下:

import {
HaloRestAPIClient,
LocalStorageTokenStore,
// FileTokenStore,
// TokenStore,
DefaultTokenProvider,
} from "@halo-dev/rest-clint-api";

// Use LocalStorageTokenStore to persistence AccessToken to localStorage (in browser only)
//you can use FileTokenStore if in the Node environment.
// If there is no suitable Token store implemention, you can implement your own token storage strategy through the TokenStore interface.
const localStorageTokenStore = new LocalStorageTokenStore();

//halo api base url.
const baseUrl = process.env.VUE_APP_BASE_URL;

const haloRestApiClient = new HaloRestAPIClient({
baseUrl: baseUrl,
});

const buildTokenProvider = (credentials) => {
return new DefaultTokenProvider(
{
...credentials,
},
baseUrl,
localStorageTokenStore
);
};

const tokenProvider = buildTokenProvider({
username: "your halo username",
password: "your password",
});
haloRestApiClient.setTokenProvider(tokenProvider);
//now you can use haloRestApiClient to build your api client

完整的例子可以点 这里

发送 Http 请求

const haloRestApiClient = new HaloRestAPIClient({
baseUrl: "https://example.halo.run",
basicAuth: { username: "user", password: "password" },
});
//build http client to perform http request
const client = haloRestApiClient.buildHttpClient();

//api parameters
const parameters = {};
//http get
client.get("https://example.halo.run", parameters);
//http post
client.post("https://example.halo.run", parameters);

Logger 日志库

安装

使用 npm 安装示例如下:

npm install @halo-dev/logger --save

主要概念

@halo-dev/logger 包支持按从最详细到最不详细的顺序指定的以下日志级别:

  • debug
  • info
  • warning
  • error

当以编程方式或通过 HALO_LOG_LEVEL 环境变量设置日志级别时,使用小于或等于您选择的日志级别时写入的任何日志都将被显示。

例如,将日志级别设置为 warning 将导致所有日志级别为 warningerror 的日志被显示。

使用示例

示例 1 - 基本使用

import * as Logger from "@halo-dev/logger";
Logger.setLogLevel ("info");

//operations will now emit info, warning, and error logs

//create a namespaced logger
const logger = Logger.createClientLogger ("posts");
const client = new AdminApiClient (/* params */);
client.post.list ()
.then (res => {
/* write an info log */
logger.info ("Successfully acquired a list of articles", res);
})
.catch (e => { /* do work */ });
});

示例 2 - 覆盖原先日志输出方式

import { HaloLogger, setLogLevel } from "@halo-dev/logger";

setLogLevel("warning");

//override logging to output to console.log (default location is stderr)
HaloLogger.log = (...args) => {
console.log(...args);
};
HaloLogger.log("hello world!");

License

MIT license

Generated using TypeDoc