🌊 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

🍀 关于开源

开源是一种精神。

开源运动所坚持的原则：

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

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

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

hanbings/flows