skyrabot/star-wars-api

Star Wars API

镜像概述和主要用途

Star Wars API 是一个受 swapi.dev 启发的GraphQL API，旨在解决原API中嵌套数据获取缓慢的问题。它将星球大战相关数据整合为GraphQL接口，提供更高效的数据查询能力，适用于需要快速获取星球大战各类资产信息的应用开发。

核心功能和特性

• TypeScript类型定义：提供客户端TypeScript类型，发布于：

  • https://www.npmjs.com/package/@skyra/star-wars-api%EF%BC%88%E5%8C%85%E5%90%8D%EF%BC%9A%60@skyra/star-wars-api%60%EF%BC%89
  • https://github.com/skyra-project/star-wars-api/packages/891643%EF%BC%88%E5%8C%85%E5%90%8D%EF%BC%9A%60@skyra-project/star-wars-api%60%EF%BC%89

• 私有部署支持：提供Docker镜像，可用于私有部署，发布于：

  • https://hub.docker.com/r/skyrabot/star-wars-api%EF%BC%88%E9%95%9C%E5%83%8F%E5%90%8D%EF%BC%9A%60skyrabot/star-wars-api%60%EF%BC%89
  • https://github.com/skyra-project/star-wars-api/pkgs/container/star-wars-api%EF%BC%88%E9%95%9C%E5%83%8F%E5%90%8D%EF%BC%9A%60ghcr.io/skyrabot/star-wars-api:latest%60%EF%BC%89

• 资产信息覆盖：提供星球大战中多种资产的详细信息，包括：

  • 电影（Films）
  • 人物（People）
  • 星球（Planets）
  • 飞船（Spaceships）
  • 物种（Species）
  • 载具（Vehicles）

使用场景和适用范围

• 需要高效查询星球大战嵌套数据的应用开发
• 基于TypeScript的项目，需类型安全的数据交互
• 希望私有部署星球大战API服务的场景
• 前端应用（如React）通过GraphQL客户端获取数据

安装

注意：仅在使用TypeScript或GraphQL schema验证时需要安装此包。包中不包含实际API，仅提供类型信息。

使用以下命令安装TypeScript类型包（可替换为其他包管理器）：

sh
npm install -D @skyra/star-wars-api

API文档

已部署版本的完整文档可查看 API的GraphQL Playground。

使用方法

以下示例基于TypeScript，JavaScript用户可将导入改为require语法并移除类型信息。

Docker部署示例

使用Docker Run

sh
# 从Dockerhub拉取并运行镜像
docker run -d -p 4000:4000 --name star-wars-api docker.xuanyuan.run/skyrabot/star-wars-api

# 或从GitHub Package Registry拉取
docker run -d -p 4000:4000 --name star-wars-api ***-ghcr.xuanyuan.run/skyrabot/star-wars-api:latest

服务启动后，可通过 http://localhost:4000 访问GraphQL Playground。

使用Fetch

ts
import type { Query } from '@skyra/star-wars-api';

interface StarWarsGraphqlApiResponse<K extends keyof Omit<Query, '__typename'>> {
  data: Record<K, Omit<Query[K], '__typename'>>;
}

fetch('https://swapi.skyra.pw/', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    query: `
      {
        getPerson(person: lukeskywalker) {
            name
            birthYear
            eyeColors
            gender
        }
      }
    `
  })
})
  .then((res) => res.json() as Promise<StarWarsGraphqlApiResponse<'getPerson'>>)
  .then((json) => console.log(json.data)); // 输出卢克·天行者的信息

使用Apollo Boost

ts
import type { Query, QueryGetPersonFuzzyArgs } from '@skyra/star-wars-api';
import ApolloClient from 'apollo-boost';
import fetch from 'cross-fetch';
import gql from 'graphql-tag';

type StarWarsGraphqlApiResponse<K extends keyof Omit<Query, '__typename'>> = Record<K, Omit<Query[K], '__typename'>>;

// 定义查询
const getPersonFuzzy = gql`
  query getPerson($person: String!) {
    getFuzzyPerson(person: $person, take: 10) {
      name
      birthYear
      eyeColors
      gender
    }
  }
`;

// 创建Apollo客户端
const apolloClient = new ApolloClient({
  uri: 'https://swapi.skyra.pw/',
  fetch
});

// 执行查询
const {
  data: { getPersonFuzzy: peopleData }
} = await apolloClient.query<StarWarsGraphqlApiResponse<'getPersonFuzzy'>, QueryGetPersonFuzzyArgs>({
  query: getPersonFuzzy,
  variables: { person: 'luke' } // 模糊查询名字包含"luke"的人物
});

console.log(peopleData); // 输出匹配的人物列表

使用Apollo Client React

Apollo Client配置

ts
// ApolloClient setup
import { ApolloClient } from 'apollo-client';
import { InMemoryCache } from 'apollo-cache-inmemory';
import { HttpLink } from 'apollo-link-http';

// 创建缓存和链接
const cache = new InMemoryCache();
const link = new HttpLink({
  uri: 'https://swapi.skyra.pw/' // API地址
});

// 导出客户端实例
export const client = new ApolloClient({
  cache: cache,
  link: link,
  name: 'graphql-star-wars-api-client',
  version: '1.0',
  queryDeduplication: false,
  defaultOptions: {
    watchQuery: {
      fetchPolicy: 'cache-and-network'
    }
  }
});

React组件使用

tsx
// Component
import React from 'react';
import gql from 'graphql-tag';
import { useQuery } from '@apollo/react-hooks';
import type { Query } from '@skyra/star-wars-api';
import { client } from './ApolloClient';

interface StarWarsGraphqlApiResponse<K extends keyof Omit<Query, '__typename'>> {
  data: Record<K, Omit<Query[K], '__typename'>>;
}

// 定义查询
const GET_PERSON_DATA = gql`
  {
    getPerson(person: lukeskywalker) {
      name
      birthYear
      eyeColors
      gender
    }
  }
`;

// React组件
export const StarWarsPerson: React.FC = () => {
  const { loading, error, data } = useQuery<StarWarsGraphqlApiResponse<'getPerson'>>(GET_PERSON_DATA, {
    client: client
  });

  if (loading) return <div>Loading...</div>;
  if (error) return <div>Error! {error.message}</div>;

  return (
    <div>
      <h2>{data?.getPerson.name}</h2>
      <p>出生年份: {data?.getPerson.birthYear}</p>
      <p>眼睛颜色: {data?.getPerson.eyeColors.join(', ')}</p>
      <p>性别: {data?.getPerson.gender}</p>
    </div>
  );
};

许可证

本项目基于 https://github.com/skyra-project/star-wars-api/blob/main/LICENSE.md 开源。