Skip to content

Latest commit

 

History

History
164 lines (113 loc) · 5.83 KB

README.md

File metadata and controls

164 lines (113 loc) · 5.83 KB
Raw

Flows

🌊 Flows

海纳百川 有容乃大！

🍀 这是什么？

洋流是一条 OAuth 客户端的辅助工具，通过低耦合的设计给用户高自定义度的接口，并且洋流集成了常见 OAuth 平台的封装，提供了光速集成第三方登录的能力。

洋流的主要特性如下：

  • 常见的 OAuth 平台适配
  • 支持自定义 State 生成器、自定义 Http 客户端、自定义 Json 解析器
  • 提供通用默认实现以便支持未适配 OAuth 平台
  • 默认 Http 客户端实现支持 Socks 代理
  • 可爱

Github OAuth 示例

洋流提供了许多的重载方法，用于应对不同情况下的请求，有些带自有请求头的，也有要求必须要 Scope 的。

// 创建 OAuth 原始处理器
OAuth<GithubAccess, GithubAccess.Wrong> oauth = new GithubOAuth(
	"id",
	"secret",
	"https://exmaple.com/api/v0/login/oauth/github/callback"
);

// 生成授权 url
String url = oauth.authorize();
// 生成带参数或指定 scope
String spec = oauth.authorize(List.of("email"), Map.of("Accept", "application/json"));
        
//解析回调的 url 并获取 token
// 输入原始 url 自动解析 code 以及 state
oauth.token("url");
// 更改回调地址
oauth.token("url", "redirect");
// 手动指定参数
oauth.token("code", "state", "redirect");
        
// 处理返回值
oauth.token("code", "state", "redirect")
	.succeed(data -> System.out.println(data.accessToken()))
	.fail(wrong -> System.out.println(wrong.errorDescription()))
	.except(throwable -> System.out.println(throwable.getMessage()));
        
// 假设请求成功 直接获取数据
GithubAccess access = oauth.token("code", "state", "redirect").data();

使用 Socks 代理

oauth.proxy(() ->
	new Request.Proxy(
		Proxy.Type.SOCKS,
		"127.0.0.1",
		10086,
		"username",
		"password"
	)
);

更换 State 生成器

默认随机生成 UUID 并设置 300 秒有效期

oauth.state(
    Lazy.of(() -> new OAuthState(300, () -> UUID.randomUUID().toString()))
);

更换 Http 客户端

默认使用 java.net.http 的 HttpClient 发起请求，无需任何第三方依赖，在 flows-extra 中还有一个 Okhttp 的实现

// 实现比较繁杂 就不展示啦 x
oauth.request(
    Lazy.of(() -> proxy == null ? new OAuthRequest() : new OAuthRequest(proxy.get()))
);

更换 Json 解析器

默认使用 Gson 作为 Json 解析器

oauth.serialization(
	Lazy.of(() -> new Serialization() {
		final Gson gson = new Gson();

		@Override
		public <T> T object(Class<T> type, String raw) {
			return gson.fromJson(raw, type);
		}

		@Override
		public <K, V> Map<K, V> map(Class<K> key, Class<V> value, String raw) {
			return gson.fromJson(raw, new TypeToken<Map<K, V>>() {
			}.getType());
		}

		@Override
		public <T> List<T> list(Class<T> type, String raw) {
			return gson.fromJson(raw, new TypeToken<List<T>>() {
			}.getType());
		}
	})
);

⚡️ 快速开始

稍后补充

🍉 一些小事情

F：这是一个什么样的项目？

Q：这是一个计划用于生产环境，长期维护和对社区友善且开放的个人项目。

F：为什么使用 JDK 17 而不是 JDK 11 甚至是 JDK 8？

Q：JDK 17 是一个 LTS （long-term support）版本，它拥有长达十年的支持时间。JDK 17 中拥有的特性例如 Record 和 Switch 模式匹配，它们都可以有效提高开发者效率。许多框架已经开始迁移到新版本的 JDK17，例如 Spring Framework 6 和 Spring Boot 3，开发者已经没有什么理由不使用新版本 JDK 了。另外，基于旧版本 JDK 的项目在完成初期开发后换用组件的几率很小，对于旧版本 JDK 的支持所带来的收益是小于成本的。

F：泛型、多个接口和复杂回调，是不是过度设计？

Q：为了保证线上业务安全，避免一个异常拖垮整个应用，尽可能获取足够详细的错误信息，进行一定程度的封装是必要的，如果用户不想编写繁杂的回调，也可以通过 Callback 对象直接获得数据或异常。

F：商业计划？

Q：本项目基于 Apache 2.0 许可证，项目本身完全是免费开源的，同样的，项目依赖库也将选择可商用开源许可的开源项目，使用本项目开发的独立项目可用于商业用途，请阅读 开源许可 部分。

⚖ 开源许可

本项目使用 Apache License, Version 2.0 许可协议进行开源。

本项目是非盈利性项目。

依据协议，本项目允许遵守协议的前提下基于本项目开发的项目进行商用，但需要注意的是，本项目中的图片（包括 Readme.md 文件中所展示的吉祥物小鱼洋流和可能出现的其他图片）不属于开源的范围 它们属于开发者 寒冰 hanbings 个人所有，是寒冰的崽子，请在复制、修改本项目时移除它们。

版权警告：吉祥物小鱼洋流图片中所使用 Flows 字样字体为商业需授权字体 Snap ITC

🍀 关于开源

开源是一种精神。

开源运动所坚持的原则：

  1. 坚持开放与共享，鼓励最大化的参与与协作。
  2. 尊重作者权益，保证软件程序完整的同时，鼓励修改的自由以及衍生创新。
  3. 保持独立性和中立性。

与来自五湖四海的开发者共同讨论技术问题，解决技术难题，促进应用的发展是开源的本质目的。

众人拾柴火焰高，开源需要依靠大家的努力，请自觉遵守开源协议，弘扬开源精神，共建开源社区！