FastComments Java SDK

为您的编码代理提供 FastComments 所需的上下文——小部件、配置、Secure SSO、REST API 和 SDK：

npx skills add fastcomments/skills

兼容 Claude Code、Codex、Cursor、Copilot、Gemini，以及所有其他由 skills CLI 支持的代理。

Maven

将 Repsy 仓库添加到您项目的 POM 中：

<repositories>
    <repository>
        <id>repsy</id>
        <name>FastComments Maven Repository on Repsy</name>
        <url>https://repo.repsy.io/mvn/winrid/fastcomments</url>
    </repository>
</repositories>

然后添加您需要的依赖：

<dependencies>
    <!-- API 客户端 -->
    <dependency>
        <groupId>com.fastcomments</groupId>
        <artifactId>client</artifactId>
        <version>3.1.1</version>
    </dependency>
    
    <!-- 核心库（包含 SSO） -->
    <dependency>
        <groupId>com.fastcomments</groupId>
        <artifactId>core</artifactId>
        <version>3.1.1</version>
    </dependency>
    
    <!-- PubSub 库（用于实时事件） -->
    <dependency>
        <groupId>com.fastcomments</groupId>
        <artifactId>pubsub</artifactId>
        <version>3.1.1</version>
    </dependency>
</dependencies>

Gradle

将 Repsy 仓库添加到您的 build.gradle 文件中：

repositories {
    mavenCentral()
    maven {
        url "https://repo.repsy.io/mvn/winrid/fastcomments"
    }
}

dependencies {
    // API 客户端
    implementation "com.fastcomments:client:3.1.1"
    
    // 核心库（包含 SSO）
    implementation "com.fastcomments:core:3.1.1"
    
    // PubSub 库（用于实时事件）
    implementation "com.fastcomments:pubsub:3.1.1"
}

库内容

该库包含三个模块：生成的 API 客户端、包含手写工具类以便更轻松使用 API 的核心 Java 库，以及用于订阅变更数据流的 pubsub 模块。

• API 客户端库文档
• 核心库文档（包括 SSO 示例）
• PubSub 库文档

公开 API 与受保护 API

对于 API 客户端，有三个类：DefaultApi、PublicApi 和 ModerationApi。DefaultApi 包含需要您的 API 密钥的方法，而 PublicApi 包含可以直接从浏览器/移动设备等发起且无需身份验证的方法。

ModerationApi 提供了一套广泛且快速的实时审核 API。每个 ModerationApi 方法都接受一个 sso 参数，可以通过 SSO 或 FastComments.com 会话 Cookie 进行身份验证。

使用经过身份验证的 API（DefaultApi）

重要提示： 在发起经过身份验证的请求之前，您必须在 ApiClient 上设置您的 API 密钥。否则，请求将失败并返回 401 错误。

import com.fastcomments.invoker.ApiClient;
import com.fastcomments.invoker.ApiException;
import com.fastcomments.api.DefaultApi;
import com.fastcomments.model.*;

public class Example {
    public static void main(String[] args) {
        // 创建并配置 API 客户端
        ApiClient apiClient = new ApiClient();

        // 必需：设置您的 API 密钥（从 FastComments 控制面板获取）
        apiClient.setApiKey("YOUR_API_KEY_HERE");

        // 使用配置好的客户端创建 API 实例
        DefaultApi api = new DefaultApi(apiClient);

        // 现在您可以发起经过身份验证的 API 调用
        try {
            // 示例：添加一个 SSO 用户
            CreateAPISSOUserData userData = new CreateAPISSOUserData();
            userData.setId("user-123");
            userData.setEmail("user@example.com");
            userData.setDisplayName("John Doe");

            AddSSOUserAPIResponse response = api.addSSOUser("YOUR_TENANT_ID", userData)
                .execute();
            System.out.println("User created: " + response);

        } catch (ApiException e) {
            System.err.println("Error: " + e.getResponseBody());
            // 常见错误：
            // - 401：API 密钥缺失或无效
            // - 400：请求验证失败
        }
    }
}

使用公共 API（PublicApi）

公共端点不需要身份验证：

import com.fastcomments.api.PublicApi;
import com.fastcomments.invoker.ApiException;

PublicApi publicApi = new PublicApi();

try {
    var response = publicApi.getCommentsPublic("YOUR_TENANT_ID", "page-url-id")
        .execute();
    System.out.println(response);
} catch (ApiException e) {
    e.printStackTrace();
}

使用审核 API（ModerationApi）

ModerationApi 用于驱动审核员控制面板。每个方法都接受一个 sso 参数，用于标识代表其发起请求的经过 SSO 身份验证的审核员：

import com.fastcomments.api.ModerationApi;
import com.fastcomments.invoker.ApiException;
import com.fastcomments.model.*;

ModerationApi moderationApi = new ModerationApi();

try {
    // 列出等待审核的评论
    ModerationAPIGetCommentsResponse response = moderationApi.getApiComments()
        .sso("YOUR_SSO_TOKEN")
        .execute();
    System.out.println(response);
} catch (ApiException e) {
    e.printStackTrace();
}

常见问题

1. 401 "missing-api-key" 错误：请确保在创建 DefaultApi 实例之前调用 apiClient.setApiKey("YOUR_KEY")。
2. API 类使用错误：服务端经过身份验证的请求请使用 DefaultApi，客户端/公共请求请使用 PublicApi。
3. API 密钥为空：如果 API 密钥为 null，SDK 将静默跳过身份验证，从而导致 401 错误。

广播 ID

你会看到在某些 API 调用中需要传入 broadcastId。当你接收到事件时，会收到这个 ID 返回，所以如果你打算在客户端乐观地应用更改，就可以据此忽略该事件（你可能会想这么做，因为它提供了最佳体验）。传入 UUID。该 ID 应足够唯一，以免在同一浏览器会话中出现两次。