菜鸟大使：菜鸟和大佬的世界是割裂的（以及为什么 Keycloak 的文档或教程如此缺乏？）
共 2064字，需浏览 5分钟
· 2022-07-08
不知不觉，写“哈德韦”专栏已经有一段时间了，最初只顾瞎写，偶然还能解决别人的问题，甚至还收到一 些付费咨询，这真的是意外的惊喜。
这时不禁萌生一个想法（幻想），好好推广自己的专栏，获得更多的咨询，甚至将来有一天靠这种咨询获得不错的收入，这样就能缓解我的程序员 35 岁危机焦虑了：即使被优化了，也不至于去送外卖：
虽然，外卖员是一个令人尊敬的职业，但我真的只喜欢写代码。但是只写代码，到了一定年龄就会被优化。这个局，怎么破？于是尝试寻求大佬的指点，你猜怎么着？大佬说这是个伪命题呀，不存在 35 岁被优化呀，只存在没有竞争力被优化。因此，要破局当然是保持竞争力了。这说得很对，但没有什么用。对于有竞争力的大佬来说，自然不存在35岁危机，当然没有这个问题；但是对于菜鸟来说呢，自然不存在竞争力，于是才面临这个问题。
菜鸟的问题，在大佬的世界里根本不存在。
总结下来就是： 菜鸟和大佬的世界是完全割裂的！菜鸟的问题，在大佬的世界里根本不存在。
本来写到这里，我就停了下来。原来自己本来是喜欢记录各种问题的解决方案的，突然发现，所有的这些问题，居然是“伪问题”，那记录解决方案，似乎突然没了意义！但是今天，老早写的一篇回答，又多了一个收藏，于是明白了一点，自己写的这些文字，还是有价值的，毕竟，这个世界上，还是菜鸟数量多。我本菜鸟一个，菜鸟的困境我感同身受，我觉得自己可以做一个菜鸟大使，去向大佬的世界取经，然后记录下以菜鸟的视角，为什么会有问题，以及该如何解决。以下就以这个被收藏的回答所针对的问题做一个例子来说明这一点：
从去年开始，陆续接到一些关于 Keycloak 的咨询，这真的是意外的惊喜。惊喜完后，我开始推测持续收到 Keycloak 相关问题的咨询的原因，大概率就是 Keycloak 的文档非常地“不详细”，导致一般人难以上手。但是作为一款优秀的开源身份认证系统，会在文档上做工粗糙吗？这是一个矛盾。
不仅有人抱怨它的文档和教程太少，而且有好几个向我咨询的网友，在问了具体的问题后，附带地问为什么找不到相关的文档。比如，最近两个咨询，都是关于 Keycloak 的 OIDC token 接口的：
对于 Keycloak 提供的接口，其入参都有哪些？为什么不在文档里说明呢？这真是怪事，我虽然直接给出具体的参数说明，但是又以 Keycloak 的开发者角度想了想，为什么不写在文档里？让使用者产生不必要的困惑？
估计是开发者在写文档时也在使用 DRY 原则吧：不要重复你自己。token 接口是 OIDC 标准里的，其入参也都是在该标准中明确过了，而我 Keycloak 只是该标准的一个具体实现而已，自然也是“继承”了 OIDC 协议中规定的入参要求的。
并不是 Keycloak 故意不将 token 接口的入参说明写在文档里，而是觉得“不应该”再重复地写进文档 。
这个现象似乎很普遍，我看了 OIDC 标准的其他实现，也是如此。比如 IdentityServer，你可以认为它是 ASP.NET 版本的 Keycloak（Keycloak 是 Java 写的），它也没有对其 token 接口做过多说明。所以：新手们困惑的文档不全问题，在老鸟看来，其实并不存在，只是新手们没找对地方。
具体地说，OIDC token 接口入参在 OIDC 协议里做了详细地描述（还有示例请求），这些协议的实现者们便不再赘述。
OIDC 的通用接口
除了这个 token 接口，还有类似的接口说明文档“缺失”吗？当然，并不是真的缺失，但是 OIDC 协议里详细描述过的接口，都不会在相关的实现里出现得很详细了，这些接口可以统称为 OIDC 通用的接口，如果你要自行实现 OIDC 协议，自然得实现所有这些接口。这些接口列表可以通过实现者公开的 /.well-kown/openid-configuration 接口获得，比如我部署的 Keycloak 和 IdentityServer 实例都在这个路径下公开了所有的 OIDC 通用接口：
- Keycloak: https://keycloak.jiwai.win/auth/realms/UniHeart/.well-known/openid-configuration
- IdentityServer: https://id6.azurewebsites.net/.well-known/openid-configuration
这些通用接口配置信息非常有用，比如之前写过一篇文章，详细描述了如何使用 IdentityServer 保护前端页面和后端 API。但是如果要换成使用 Keycloak 来保护它们，完全不用修改被保护的前端和后端应用的代码，只需要修改相应的 OIDC 通过接口的 url 即可。
使用 IdentityServer 保护 Web 应用（AntD Pro 前端 + SpringBoot 后端）